Kura/HardwareTargets

Overview

This reference provides instructions on adding a new hardware target to Kura. Before beginning, make sure you have setup a full Kura development environment. The only two hard requirements at this time for running Kura are:

• Linux Operating System
• Java SE 7

Memory requirements will vary greatly depending on the types of applications running within the framework and the amount/frequency of messages being sent and received. Also note that some functionality relies on native libraries. If the libraries supplied in Kura do not match your target architecture, you will need to compile your own native libraries.

Code Modifications

The code changes required to add a new hardware target to Kura are minimal. For the remainder of this document, "hello-hw" will refer to the new example target hardare to be setup. First, modify kura/distrib/pom.xml and add the below Maven profile to the profiles section:

 <profile>
   <id>hello-hw</id>
   <activation>
       <activeByDefault>true</activeByDefault>
   </activation>
   <build>
     <resources>
         <resource>
             <directory>src/main/resources</directory>
             <filtering>true</filtering>
         </resource>
     </resources>
     <plugins>
         <plugin>
             <groupId>org.codehaus.mojo</groupId>
             <artifactId>properties-maven-plugin</artifactId>
             <version>1.0-alpha-1</version>
             <executions>
                 <execution>
                     <phase>initialize</phase>
                     <goals>
                         <goal>read-project-properties</goal>
                     </goals>
                     <configuration>
                         <files>
                             <file>${basedir}/build.properties</file>
                             <file>${basedir}/config/kura.build.properties</file>
                         </files>
                     </configuration>
                 </execution>
             </executions>
         </plugin>
         <plugin>
             <groupId>org.codehaus.mojo</groupId>
             <artifactId>buildnumber-maven-plugin</artifactId>
             <version>1.0</version>
             <executions>
                 <execution>
                     <phase>validate</phase>
                     <goals>
                         <goal>create-timestamp</goal>
                     </goals>
                 </execution>
             </executions>
         </plugin>
         <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-antrun-plugin</artifactId>
             <version>1.7</version>
             <executions>
               <execution>
                   <id>hello-hw-jars</id>
                   <phase>install</phase>
                   <goals>
                       <goal>run</goal>
                   </goals>
                   <configuration>
                     <target>
                         <property name="buildNumber" value="buildNumber" />
                         <property name="project.version" value="${project.version}" />
                         <property name="project.build.profile" value="${project.build.profile}" />
                         <property name="project.build.directory" value="${project.build.directory}" />
                         <property name="build.name" value="hello-hw" />
                         <property name="target.device" value="hello-hw" />
                         <property name="kura.os.version" value="debian" />
                         <property name="kura.arch" value="armv6_hf" />
                         <property name="kura.mem.size" value="256m" />
                         <property name="kura.install.dir" value="${kura.install.dir}" />
                         <ant antfile="${basedir}/src/main/ant/build_equinox_distrib.xml"
                             target="dist-linux" />
                     </target>
                   </configuration>
               </execution>
            </executions>
         </plugin>
     </plugins>
   </build>
 </profile>

The profile will assist in creating a shell script installer for the targeted hardware. If the hardware is running a Debian based OS, the "raspberry-pi" and "beaglebone" profiles can be used as references for creating a Debian package. There is also information on the use of jdeb in Kura here.

The majority of the profile can be used as is, the attributes that must be edited are:

• <id> - This is the profile ID and must be unique
• <property name="buid.name"> - This is used to name the output artifacts
• <property name="target.device"> - Kura uses this to occasionally run specific code for a specific target
• <property name="kura.os.version"> - Similar to target.device, this is sometimes used for executing specific code
• <property name="kura.arch"> - This is used to identify the correct native libraries to load
• <property name="kura.mem.size"> - This sets the Xms, Xmx, and MaxPermSize Java VM memory properties

Code Additions

Each hardware target has a directory in kura/distrib/src/main/resources (ex: kura/distrib/src/main/resources/raspberry-pi). For simplicity, use the below code to copy an existing target platform:

 mkdir kura/distrib/src/main/resources/hello-hw
 cp -R kura/distrib/src/main/resources/raspberry-pi/* kura/distrib/src/main/resources/hello-hw/.

An optional step would be to create a copy of the *-nn directory for the new target. This would create a version of the build without networking support. This is useful if you do not want Kura to assist in managing network settings.

Each file in the new directory should be reviewed and edited to match the new target. Below is a brief overview of each file:

• firewall.init - This file is used to setup the linux firewall during installation. The default file opens ports for HTTP (management UI), DNS, DHCP, and 1450 for remote bundle deployment (mToolKit).
• jdk.dio.properties - This file contains the default Device I/O properties for this hardware target. It should be edited in most cases.
• kura.properties - This file contains various system properties. The values should be examined and updated to match the new target.
• kura_install.sh - This is the base installer script. For most situations it should not be edited.
• kura_upgrade.sh - This is the base upgrade script. For most situations it should not be edited.
• kuranet.conf - This file contains basic information about the available network interfaces. Interfaces should be added or removed as needed using the original file as a template.
• log4j.properties - This file contains settings for the logger utility. The provided settings should work fine in most cases.
• recover_dflt_kura_config.sh - Helper utility to assist in recovering configurations. This file should not be edited.
• snapshot_0.xml - This is the main configuration file for Kura. A good practice is to use the copied configuration file to start Kura for the first time. After Kura has been configured to the desired starting conditions, the updated snapshot file can be obtained through the management UI (Settings -> Snapshots) or from the /opt/eclipse/kura/data/snapshots directory. The latest snapshot will have the largest numeric value. This updated file can then be renamed to snapshot_0.xml and copied over to the hardware directory.

Native Libraries

Coming Soon

Artifacts

After a successful Maven build, the new target hardware should have artifacts in kura/distrib/target. Most important of which is an installer shell script that should be used to install Kura on the new target hardware.

Device I/O Properties

Each target hardware should define its Device I/O hardware bindings. This association is done by editing the jdk.dio.properties file.

The jdk.dio.properties file for the Raspberry Pi B+, in example, looks as follows:

 5 = deviceType: gpio.GPIOPin, pinNumber:5, name:GPIO05 
 6 = deviceType: gpio.GPIOPin, pinNumber:6, name:GPIO06
 12 = deviceType: gpio.GPIOPin, pinNumber:12, name:GPIO12
 13 = deviceType: gpio.GPIOPin, pinNumber:13, name:GPIO13
 16 = deviceType: gpio.GPIOPin, pinNumber:16, name:GPIO16
 17 = deviceType: gpio.GPIOPin, pinNumber:17, name:GPIO_GEN0
 18 = deviceType: gpio.GPIOPin, pinNumber:18, name:GPIO_GEN1
 19 = deviceType: gpio.GPIOPin, pinNumber:19, name:GPIO19
 20 = deviceType: gpio.GPIOPin, pinNumber:20, name:GPIO20
 21 = deviceType: gpio.GPIOPin, pinNumber:21, name:GPIO21
 22 = deviceType: gpio.GPIOPin, pinNumber:22, name:GPIO_GEN3
 23 = deviceType: gpio.GPIOPin, pinNumber:23, name:GPIO_GEN4
 24 = deviceType: gpio.GPIOPin, pinNumber:24, name:GPIO_GEN5
 25 = deviceType: gpio.GPIOPin, pinNumber:25, name:GPIO_GEN6
 26 = deviceType: gpio.GPIOPin, pinNumber:26, name:GPIO26
 27 = deviceType: gpio.GPIOPin, pinNumber:27, name:GPIO_GEN2
 
 gpio.GPIOPin = initValue:0, deviceNumber:0, direction:3, mode:-1, trigger:3
 uart.UART = baudRate:19200, parity:0, dataBits:8, stopBits:1, flowControl:0

The file defines the default hardware configuration for each Device I/O peripheral. Most of the times the default properties will have to be specified only for GPIOs, as other peripherals will not likely have a default configuration.

Each line is composed be a key/value pair. The numeric keys are the indexes used to access the peripherals with the DeviceManager.open() API, while the value is always a comma separated list of properties. Refer to OpenJDK Device I/O javadoc for further details.

The string keys are used to set default parameters for all the other key/value pairs of the same deviceType.

The following properties apply for GPIO pins:

• diviceType: name of the implementation class inside jdk.dio. always gpio.GPIOPin
• pinNumber: logical pin number used to access the GPIO
• name: a human readable description of the pin
• initValue: starting value of the pin. Only meaningfull for Outputs
• deviceNumber: number of the logic GPIO controller. Usually 0
• direction: direction of the pin. High or Low if Output, Pull Up, Push Down if Input
• mode: mode of the pin. Only meaningfull for Inputs
• trigger: trigger mode. Only meaningfull for inputs