NetComm Wireless Software Development Kit Feature Spotlight

1. NetComm WirelessSoftware Development KitFeature Spotlight

2. The Software Development Kit NetComm Wireless provide a software development kit (SDK) to allow third parties to develop custom software applications for our routers. As our routers operate a linux-based kernel, the SDK should be unpacked and installed on a Linux machine. To get you started, the SDK includes two examples – a kernel driver and a userspaceapplication.

3. The Software Development Kit • Users can create their own applications to extend the functionality of the device. • Applications can be distributed as ‘packages’ in IPK format and may be installed either locally on a NetComm Wireless router via the Web-UI upload page, or remotely via SMS/TR-069. • Packages that you create can easily be inserted into regular firmware upgrade images for easy mass-deployment.

4. System overview • The NetComm Wireless platform is designed for ease of development. As such, it has relatively large reserves of FLASH, SDRAM and computing power. It is also quite forgiving of developer errors and can recover from most failures. • RECOVERY VS. MAIN • The router has two independent systems, each with its own kernel and file system. These are referred to as “Main” and “Recovery”. You can always use one system to restore the other. • BOOT SEQUENCE • The bootloader attempts to load the main system by default. If that fails, it loads the recovery system. If that fails too, the bootloader attempts to fetch a recovery system kernel and rootfs from an external TFTP server. On success, those images are automatically flashed. You can force the router to boot into recovery mode by using the reset button.

5. The Runtime Database (RDB) The Runtime Database is an inter-process communication and storage system using variables. Most applications on the router use the RDB either directly or indirectly. This provides comprehensive device status and configuration via a simple key value pairsystem Processes can create, read or write variables. They can also be notified if any of the variables are changed. Access can be controlled with a user-based access control scheme. Database variables are identified by name strings, usually in field.field.field notation. Names tend to be self-explanatory and can be used to group data into records e.g. “link.profile.1.auth_type” and “link.profile.1.status” are variables related to link profile 1. Database variables can contain arbitrary binary data, but most contain human readable strings. Database variables can also contain flags that describe properties, for example, a variable can be “persistent”, which is a variable that survives a reboot.

6. The Runtime database Variables are subject to access control permissions, similar to Unix files. There are three permission groups (owner, group & others) and four flags in each group (read, write, erase, perm). By manipulating the permissions, a task can, for instance, create a variable everyone can write to, but only the owner may read (e.g. password check). Database variables have an additional ‘flags’ field which denotes special variable properties and behaviour:

7. The command line A command line tool is provided to manipulate the RDB, for use within scripts and on the system’s command line. This is a single binary file that may be called using one of the three names rdb_get, rdb_set or rdb_wait. rdb_get Used to fetch a list of variables or read a single variable. Here is an example of how to retrieve all variables with the “snmp” string: root:# rdb_get –L snmp service.snmp.enable 0 service.snmp.name.readwrite private service.snmp.name.readonly public

8. The command line • How to retrieve signal strength (RSSI): • root:~# rdb_get wwan.0.radio.information.signal_strength • -80dBm • root:~# • How to retrieve the APN for a particular profile: • root:~# rdb_get link.profile.1.apn • telstra.extranet • root:~# • How to retrieve WWAN IP Address for Profile 1: • root:~# rdb_get link.profile.1.iplocal • 123.209.5.2 • root:~#

9. The command line rdb_set Used to set a variable. Here’s an example of creating a new variable: root:# rdb_settestvar test Read back the new variable: root:# rdb_gettestvar test How to configure APN for Profile 2: root:~# rdb_set link.profile.2.apn testapn Confirming that the APN was configured to “testapn” root:~# rdb_get link.profile.2.apn testapn root:~#

10. The command line rdb_wait Used to launch a background task waiting for the variable to be updated. root:# rdb_waittestvar && echo "Got '`rdb_gettestvar`'" & Now you can set the variable: root:# rdb_settestvar 'new value' root:# Got 'new value' [2] + Done rdb_waittestvar && echo "Got \'"$(...)"\'"

11. Some final words on SMS Forwarding SMS Diagnostics and SMS Forwarding may be used at the same time When SMS forwarding is enabled, all messages are passed to the downstream device, including SMS Diagnostics messages. The downstream device should be capable of filtering out the irrelevant messages. SMS messages may be forwarded a TCP port and a UDP port simultaneously. An optional feature for use in OpCos rather than GDSP use is that SMS messages may also be forwarded to another mobile numberin addition to via TCP and/or UDP.

12. Launching your application There are a few ways of launching your new application: launch it at system boot by inserting a line into /etc/inittab add a system startup script create an RDB template RDB TEMPLATES Templates are scripts which are triggered based on system events – changes to RDB variables. Templates are stored in /etc/cdcs/conf/mgr_templates/. They are mostly scripts with a grammar extension to allow them to specify a list of RDB variables to which they are sensitive. All templates run once at boot time and then every time any of the sensitive variables are written, even if the value remains the same.

13. Templates Here is an example of a template which sends an SMS when the signal strength falls below -100dBm and sends an SMS when the signal strength recovers: #!/bin/shSIGNAL="?<wwan.0.radio.information.signal_strength>;"log() {logger -t "signal_sms.template" -- "$@"}dBm="-100"recv="0412345678"SIGNAL=$(echo "$SIGNAL" | sed 's/dBm//g')# get previous signal strengthPREV_SIGNAL=$(rdb_get "wwan.0.radio.information.signal_strength.prev")if [ -z "$PREV_SIGNAL" ]; thenPREV_SIGNAL=0fi# if raising edge is detectedif [ $PREV_SIGNAL -ge $dBm -a $SIGNAL -lt $dBm ]; thenlog "[sendsms] signal drops to $SIGNAL / below $dBm"sendsms -- "$recv" "signal drops to $SIGNAL / below $dBm" DIAG# if failling edge is detectedelif [ $PREV_SIGNAL -lt $dBm -a $SIGNAL -ge $dBm ]; thenlog "[sendsms] signal recovers to $SIGNAL / above $dBm"sendsms -- "$recv" "signal recovers to $SIGNAL / above $dBm" DIAGfi# store current to previousrdb_set -- "wwan.0.radio.information.signal_strength.prev" "$SIGNAL”

14. Templates • Below is a very basic template which runs every time the first connection is made and the WAN IP address is available: • #!/bin/sh • WANIP="?<link.profile.1.iplocal>;" • echo ''$WANIP'' >/tmp/wanip.txt • ftpput some-remote-server.com 3g_ip.txt /tmp/wanip.txt • This template places any new 3G IP address into a file and uploads that file via FTP to a remote machine - a very primitive form of creating a dynamic DNS system.

15. LEDs The LEDs are available via the standard sysfs interface. When using them for custom applications, care must be taken to avoid conflicts with existing functionality. In general, normal operation of the LEDs tends to operate via triggers (see below), which can be switched off. There are a few cases where LED state is also controlled or modified within RDB templates, e.g. RSSI and DCD LEDs. For most simple applications, it is sufficient to update the LED state about once per second, thus overriding the templates. Beyond that, it may be necessary to disable the relevant templates.

16. User interface (Appweb) The Web-based user interface is currently built around the Appweb server. This server supports server side scripting and is linked with the RDB system, such that server side (ESP) scripts have access to RDB variables. Web interface related files are located in the /www directory, which acts as the web server root. CUSTOM MENUS The NetComm Wireless platform has a mechanism for easily adding menu items, without having to edit existing files. Part of the menu bar is generated dynamically from the contents of the /www/usermenu directory. This directory contains simple text files, whose name is used as the menu entry and whose content is the link to invoke. For example, this command line sequence adds a link that returns the name of the current 3G provider: root:# cd /www/usermenu root:/www/usermenu# echo "cgi-bin/rdb.cgi?wwan.0.service_provider_name" > "Provider" /etc/init.d/rc.d/usermenu

17. Further information More information: This presentation is a brief introduction to the possibilities available with the Software Development Kit. For more information on the SDK please see the SDK documentation available on the NetComm Wireless website.