NetComm Wireless

Software Development KitFeature Spotlight

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 userspace application.

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.

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. MAINThe 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 SEQUENCEThe 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.

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 pair system

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.

The Runtime databaseVariables 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:

FLAG DESCRIPTION

PERSISTVariables with this flag set will be automatically shadowed in the system settings file. That is, they get populated from the settings file at system start and after that, the settings file on disk will mirror the contents.

CRYPTVariables with this flag set use reversible encryption on their data fields when exported to an external file. This must be used in conjunction with PERSIST, and is set for passwords, PIN numbers, etc.

HASHSimilar to crypt, but uses a one-way cryptographic hash. Rarely used - it can be used to store a password in a non-reversible way.Useful for checking credentials - same passwords result in the same hash.

READ_ONCE Variable self destructs after one read. Used for temporary keys or other credentials. Avoids inadverted leaking of critical information.

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_getUsed 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 snmpservice.snmp.enable 0service.snmp.name.readwrite privateservice.snmp.name.readonly public

The command line

How to retrieve signal strength (RSSI):

root:~# rdb_get wwan.0.radio.information.signal_strength-80dBmroot:~#

How to retrieve the APN for a particular profile:

root:~# rdb_get link.profile.1.apntelstra.extranetroot:~#

How to retrieve WWAN IP Address for Profile 1:

root:~# rdb_get link.profile.1.iplocal123.209.5.2root:~#

The command linerdb_setUsed to set a variable. Here’s an example of creating a new variable:

root:# rdb_set testvar test

Read back the new variable:

root:# rdb_get testvartest

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.apntestapnroot:~#

The command line

rdb_waitUsed to launch a background task waiting for the variable to be updated.

root:# rdb_wait testvar && echo "Got '`rdb_get testvar`'" &

Now you can set the variable:

root:# rdb_set testvar 'new value'root:# Got 'new value'[2] + Done rdb_wait testvar && echo "Got \'"$(...)"\'"

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 number in addition to via TCP and/or UDP.

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.

TemplatesHere 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”

Templates

Below is a very basic template which runs every time the first connection is made and the WAN IP address is available:

#!/bin/shWANIP="?<link.profile.1.iplocal>;"echo ''$WANIP'' >/tmp/wanip.txtftpput 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.

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.

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 MENUSThe 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/usermenuroot:/www/usermenu# echo "cgi-bin/rdb.cgi?wwan.0.service_provider_name" > "Provider"/etc/init.d/rc.d/usermenu

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.