NetComm Wireless
Software Development Kit
Feature 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/TR069.
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. 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.
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 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:
FLAG
DESCRIPTION
PERSIST
Variables 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.
CRYPT
Variables 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.
HASH
Similar 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_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
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:~#
The command line
rdb_set
Used 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 testvar
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:~#
The command line
rdb_wait
Used 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.
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/sh
SIGNAL="?<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 strength
PREV_SIGNAL=$(rdb_get "wwan.0.radio.information.signal_strength.prev")
if [ -z "$PREV_SIGNAL" ]; then
PREV_SIGNAL=0
fi
# if raising edge is detected
if [ $PREV_SIGNAL -ge $dBm -a $SIGNAL -lt $dBm ]; then
log "[sendsms] signal drops to $SIGNAL / below $dBm"
sendsms -- "$recv" "signal drops to $SIGNAL / below $dBm" DIAG
# if failling edge is detected
elif [ $PREV_SIGNAL -lt $dBm -a $SIGNAL -ge $dBm ]; then
log "[sendsms] signal recovers to $SIGNAL / above $dBm"
sendsms -- "$recv" "signal recovers to $SIGNAL / above $dBm" DIAG
fi
# store current to previous
rdb_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/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.
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 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
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.