November 29, 2016

Tracking Changes using Audit feature

A common requirement in Maximo is to track changes made by users on a specific object (database table). In Maximo terms this is called 'Audit Tracking'.
In this post I will describe how to enable audit tracking for a specific set of attributes of an object and how to display the updates in a separate tab of the corresponding application.
I will use the Assets application for this tutorial and here is the final outcome I have achieved.




There are three configurations to be implemented for this:
  1. Enable audit of the main object and select attributes to be audited
  2. Define relationship to the audit table
  3. Customize the application to display the audit log from the UI

Enable audit


First step is to enable the auditing of the table you want to monitor.
Open the Database Configuration application, select ASSET object and check the Audit Enabled flag.


You now have to select which fields will trigger the audit record. Switch to the Attributes tab and select the Enable Auditing flag for STATUS, SERIALNUM, LOCATION, DESCRIPTION fields.

Enable admin mode, apply configuration changes and disable admin mode.
A new database table A_ASSET will be created and, from now on, all the changes to the audited fields will be traced in the audit table.

Define relationship


In order to be able to display the audit records we have to create a relationship from the ASSET table to the A_ASSET table.
Open the Database Configuration application, select ASSET object and in the Relationships tab create the following relationship.
  • Relationship: A_ASSET
  • Child Object: A_ASSET
  • Where Clause: assetnum=:assetnum and siteid=:siteid

Customize application


Now you can use the relationship you have just created to display records from the child A_ASSET audit table in the Asset application.
Open Application Designer application, select the ASSET application and export the app's XML definition.
Backup the file and edit it with a text editor. Paste the text below before the last </tabgroup> before the </clientarea> tag.

<tab id="myhist" label="History">
  <section id="myhist_grid1">
    <sectionrow id="myhist_grid1_11">
      <sectioncol id="myhist_grid1_11_1">
        <section id="myhist_grid1_11_1_1">
          <multiparttextbox dataattribute="assetnum" descdataattribute="description" id="myhist_grid1_1"/>
        </section>
      </sectioncol>
    </sectionrow>
  </section>
  <table id="myhist_t1" inputmode="readonly" label="Asset history" orderby="EAUDITTIMESTAMP desc" relationship="A_ASSET">
    <tablebody displayrowsperpage="10" id="myhist_t1_tb">
      <tablecol dataattribute="SERIALNUM" id="myhist_t1_SERIALNUM"/>
      <tablecol dataattribute="STATUS" id="myhist_t1_STATUS"/>
      <tablecol dataattribute="LOCATION" id="myhist_t1_LOCATION"/>
      <tablecol dataattribute="DESCRIPTION" id="myhist_t1_DESCRIPTION"/>
      <tablecol dataattribute="EAUDITUSERNAME" id="myhist_t1_EAUDITUSERNAME" label="Changed By"/>
      <tablecol dataattribute="EAUDITTIMESTAMP" id="myhist_t1_EAUDITTIMESTAMP" label="Changed Date"/>
    </tablebody>
  </table>
</tab>
</tabgroup>
...
</clientarea>


June 3, 2016

Watson IoT MQTT APIs walkthrough


After several experiments with IBM Watson IoT Platform I have decided to take a step back and play MQTT manually to really understand how it works. In this post I will walk through my experiments with of the Watson IoT Platform MQTT messaging API for devices, applications and gateways.

Prerequisites

First of all you need an account on IBM Watson IoT Platform on Bluemix. In all cases you need to create your own Internet of Things Platform service and create your own device type and device. I suggest you to follow the IoT Starter tutorial if you are on familiar with Watson IoT.

Another important preliminary step is to have an MQTT client to simulate MQTT calls. I have decided to use MQTT Spy tool. Download it from here and have it ready on your PC. There is a very good tutorial here if you want to learn more.
If you don't like it you can also try MQTT Lens.


Publish event from a device


This is the most simple example. A device sending MQTT messages to the cloud.
The device must be first registered on Watson IoT Platform. On you IBM Bluemix dashboard, click on the Internet of Things Platform service. Open the dashboard by clicking on the 'Launch Dashboard' button.
Open the Devices page and click on the Create Device button. First create a Device Type and then a new Device with the following details:
  • Type: TestDeviceType
  • Name: TestDev1
  • Security token: test1234
A summary page will be displayed with the device information needed for the connection.

Now we are ready to send our first message.
Devices use the following identification/authentication information (detailed documentation):
  • Client ID in formatted as d:[OrgId]:[DeviceType]:[DeviceId]
  • Username is use-token-auth
  • Password is the authentication token generated during device registration
  • Topic for publishing events is iot-2/evt/status/fmt/json

Create an new connection on MQTT Spy (replace [OrgId] with your Organization ID).
  • Protocol version: MQTT 3.1.1
  • Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
  • Client ID: d:[OrgId]:TestDeviceType:TestDev1
  • Username: use-token-auth
  • Password: test1234



Now you can publish the first MQTT message.
  • Topic: iot-2/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT"}}



Now open the Watson IoT device details and click on the Publish button on MQTT Spy. You should see the incoming message like this.




Publish event from an application on behalf of the device

The Watson Iot Platform allow to define external applications that can publish events on behalf of any device and subscribe to device events. In this tutorial we will publish a message for the Dev1 device and subscribe to its events.

We first need to define the application on Watson Iot Platform Dashboard. Open the Access and API Keys tab, then click on Generate API Keys button. Take note of the API Key and Authentication Token.



Applications use the following identification/authentication information (detailed documentation):
  • Client ID in formatted as d:[OrgId]:[AppId]
  • Username id the API Key generated during registration
  • Password is the Authentication Token generated during registration
An application can publish events as if they came from any registered device.
  • Topic for publishing events is iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json


Create an new connection with your MQTT client.
  • Protocol version: MQTT 3.1.1
  • Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
  • Client ID: a:[OrgId]:App1
  • Username: enter your API Key
  • Password: enter your Authentication Token


Now you can publish a message on behalf of device TestDev1 used before.
  • Topic: iot-2/type/TestDeviceType/id/TestDev1/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm App1"}}



Subscribe to device events from an application


An application can subscribe to events from one or more devices using topic iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json
The MQTT wildcard character '+' can be used to subscribe to more than one type of event.

On MQTT Spy subscribe to all events from the TestDev1 device using topic iot-2/type/TestDeviceType/id/TestDev1/evt/+/fmt/json


Play with MQTT Spy and see how App 1 is notified when publishing events from the device. Try changing the subscription topic as well.



Gateway


Gateways can publish events from itself and on behalf of any device connected to it. In this tutorial we will publish a message for the Dev1 device and see how it is received from the subscribed app.

Open the Devices page on your Watson IoT dashboard and click on the Add Device button. First create a Gateway Type and then a new Gateway.
  • Type: TestGwType
  • Name: TestGw1
  • Security token: test1234


Gateways use the following identification/authentication information (detailed documentation):
  • Client ID in formatted as g:[OrgId]:[GwType]:[GwId]
  • Username is use-token-auth
  • Password is the authentication token generated during device registration
Note that these information are very similar to the device connection properties but the Client ID has now a 'g' prefix instead of 'd'.
A gateway can publish events on behalf of a device.
  • Topic for publishing events is iot-2/type/[DeviceType]/id/[DeviceId]/evt/[EventId]/fmt/json

Create an new connection with your MQTT client.
  • Protocol version: MQTT 3.1.1
  • Server URI: [OrgId].messaging.internetofthings.ibmcloud.com:1883
  • Client ID: g:[OrgId]:TestGwType:TestGw1
  • Username: use-token-auth
  • Password: test1234


Publish an event for the gateway:
  • Topic: iot-2/type/TestGwType/id/TestGw1/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm Gw1"}}
Publish an event for the device:
  • Topic: iot-2/type/TestDeviceType/id/TestDev1/evt/status/fmt/json
  • Data: {"d":{"status":"Hello Watson IoT", "sender":"I'm Gw1"}}
Note haw the App1 subscription is receiving the events from the device. You can also try to subscribe to the gateway's events.


References


IBM Watson IoT Platform documentation
MQTT Spy tutorial


May 7, 2016

Install Kura on Raspberry PI


Eclipse Kura is an Open Source project that provides a platform for building IoT gateways. It is a smart application container that enables remote management of such gateways and provides a wide range of APIs for allowing you to write and deploy your own IoT application. Kura runs on top of the Java Virtual Machine (JVM) and leverages OSGi, a dynamic component system for Java, to simplify the process of writing reusable software building blocks. Kura APIs offer easy access to the underlying hardware including serial ports, GPS, watchdog, USB, GPIOs, I2C, etc. It also offer OSGI bundle to simplify the management of network configurations, the communication with IoT servers, and the remote management of the gateway.

In this post I will describe my own quick way of installing and configuring Kura on a Raspberry PI board. Please refer to the official Kura installation guide for more information.


Prerequisites

  • Raspberry PI 2 or 3 with a recent version of Raspbian OS and connected to the internet. See my quick start.


Download Kura package

First of all you need to download Kura on your PI from this page.
Identify the package to be downloaded from the list. I typically use the Extended, No Net, with Web UI version - Kura 1.4.0 Extended Download: Raspbian (Model 2, No Net, with Web UI).
Versions with network are a little bit more challenging to install.

Download the selected package using the web browser or you can use this command:
cd /tmp
wget https://s3.amazonaws.com/kura_downloads/raspbian/release/1.4.0/kura_1.4.0_raspberry-pi-2-nn_installer.deb


Install Kura

First update your system's package list by entering the following command:
sudo apt-get update

Install the Kura package:
sudo dpkg -i kura_1.4.0_raspberry-pi-2-nn_installer.deb

Ignore the dependency problems warnings and fix the installation by running the following command:
sudo apt-get install -f

You can now delete the Kura package:
rm kura_1.4.0_raspberry-pi-2-nn_installer.deb

Reboot the Raspberry Pi
sudo reboot

Kura server will be restarted automatically so you should be able to access the Kura administrative UI - http://[HOST]/kura
Default login is admin/admin

To view Kura logs type the following command
tail -f /var/log/kura.log

It is strongly suggested to change admin password. This can be done by selecting the WebConsole service from the UI.


Disable CloudService (optional)

In my examples I will connect Kura to IBM Watson IoT Platform. The CloudService is a proprietary service and not appropriate for connecting to Watson IoT so we can disable it permanently.

Edit the Kura /opt/eclipse/kura/kura/config.ini file and modify the osgi.bundles parameter by changing the action for the https://developer.ibm.com/recipes/kura/plugins/org.eclipse.kura.core.cloud_*.jar from "start" to "stop".

May 6, 2016

Raspberry PI installation and first setup

In this post I will describe how to install the Raspbian operating system on a Raspberry PI 2 or 3 and some basic configuration settings to start your IoT projects.
The described procedure will not require a display and keyyboard and can be performed just connecting the PI to your router using a LAN cable.



Raspbian OS installation

First of all you need to download the latest Raspbian OS image from here. Choose the full version not the lite one.
If you are running on Windows, download the Win32DiskImager utility from here and use it to flash the iso image to the SD card. Refer to this guide for more details.
If you are running on Linux or MaxOS look here.

Now you can insert the SD card into the Raspberry PI slot and power it on.

Basic configuration

To avoid the need of connecting a display and keyboard, I typically just plug a LAN cable from my home router to the PI and get it's IP address from the router administrative console which typically is accessible at http://192.168.1.1/ or http://192.168.1.0/.

You can now use any SSH client like Putty to connect to the PI. The default user and passwords are pi/raspberry.


Expand filesystem (IMPORTANT)

The Raspbian ISO image is not configured to use all the SD card available memory so you need to expand the filesystem to use all the available space.
Enter the raspi-config utility:
sudo raspi-config

Choose option ‘1 Expand Filesystem’.


Exit raspi-config and it should ask to reboot. You can also manually reboot the Raspberry PI with this command:
sudo reboot

Set keyboard (optional)

Run raspi-config again if needed.

Choose ‘5 Internationalisation Options’.
Set the correct timezone and keyboard layout.
I typically leave the default locale en_GB.UTF-8 UTF-8.


Install VNC server

Next step is to install and configure a VNC server to be able to access the PI graphical UI through a network connection.
To install the TightVNC package type:
sudo apt-get install tightvncserver


Run the VNC Server which will prompt you to enter a password and an optional view-only password:
vncserver :1 -geometry 1280x800 -depth 16

Set your password and don't forget it. I typically do no specify a view-only password.

Now the VNC server on port 1 should be started and you can use any VNC client to connect to the PI. I personally use the RealVNC client.

To automatically start the VNC server when the PI boots follow this instructions.

Log into a terminal on the Pi as root:
sudo su

Navigate to the directory /etc/init.d/:
cd /etc/init.d/

Crete a vncboot file using vi command
vi vncboot

The vi editor commands (more info) are very cryptic, follow the instructions below:
  • Press i to enter insert mode.
  • Paste the script below (right click on the console to paste).
  • Exit vi saving the file by typing: ESC :wq

#! /bin/sh
# /etc/init.d/vncboot

### BEGIN INIT INFO
# Provides: vncboot
# Required-Start: $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start VNC Server at boot time
# Description: Start VNC Server at boot time.
### END INIT INFO

USER=pi
HOME=/home/pi

export USER HOME

case "$1" in
 start)
  echo "Starting VNC Server"
  #Insert your favoured settings for a VNC session
  su - $USER -c "/usr/bin/vncserver :1 -geometry 1280x800 -depth 16"
  ;;

 stop)
  echo "Stopping VNC Server"
  /usr/bin/vncserver -kill :1
  ;;

 *)
  echo "Usage: /etc/init.d/vncboot {start|stop}"
  exit 1
  ;;
esac

exit 0

Make this file executable:
chmod 755 vncboot

Enable dependency-based boot sequencing:
update-rc.d -f lightdm remove
update-rc.d vncboot defaults

Reboot your Raspberry Pi
reboot

Wait for 1 or 2 minuter for the PI to restart and try connecting to the VNC server to check if it automatically starts.
Look here for more details about VNC setup.

If you have a RasPI 3 you can now easily configure the WiFi connection from the desktop. After having configured the WiFi, disconnect the LAN cable. Don't forget that a new IP address will be assigned.

Port Mapping (optional)

If you have installed the Raspberry PI at your house and want to access it remotely you can define port mappings on your router.
  • SSH: 22 > 10022
  • VNC: 5901 > 15901
  • HTTP: 80 > 10080
I prefer to change the ports for security reasons and to allow more than one device to be mapped.