This is an old revision of the document!


SDK

NetModule routers are shipping with a Software Development Kit (SDK) which offers a simple and fast way to implement customer-specific functions and applications. It consists of:

  1. An SDK host which defines the runtime environment (a so-called sandbox), that is, controlling access to system resources (such as memory, storage and CPU) and, by doing so, catering for the right scalability.
  2. An interpreter language called arena, a light-weight scripting language optimized for embedded systems, which uses a syntax similar to ANSI-C but adds support for exceptions, automatic memory management and runtime polymorphism on top of that.
  3. A NetModule-specific Application Programming Interface (API), which ships with a comprehensive set of functions for accessing hardware interfaces (e.g. digital IO ports, GPS, external storage media, serial ports) but also for retrieving system status parameters, sending E-Mail or SMS messages or simply just to configure the router.

Anyone, reasonably experienced in the C language, will find an environment that is easy to dig in. However, feel free to contact us via router@support.netmodule.com and we will happily support you in finding a programming solution to your specific problem.

The Language

The arena scripting language offers a broad range of POSIX functions (like printf or open) and provides, together with tailor-made API functions, a simple platform for implementing any sort of applications to interconnect your favourite device or service with the router. Here comes a short example:

/* We are going to eavesdrop on the first serial port
* and turn on lights via a digital I/O output port ,
* otherwise we 'd have to send a short message .
*/
for ( attempts = 0; attempts < 3; attempts ++) {
if ( nb_serial_read (" serial0 ") == " Knock Knock !") {
nb_serial_write (" serial0 ", "Who 's there ?");
if ( nb_serial_read (" serial0 ") == " Santa ") {
printf (" Hurray !\n");
nb_dio_set (" out1 ", 1);
}
}
}
nb_sms_send (" +123456789 ", "No presents this year :(")

A set of example scripts can be downloaded directly from the router, you can find a list of them in the appendix. The manual which can be obtained from the NetModule support web page gives a detailed introduction of the language, including a description of all available functions.

SDK API Functions

The current range of API functions can be used to implement the following features:

  1. Send/Retrieve SMS
  2. Send E-mail
  3. Read/Write from/to serial device
  4. Control digital input/output ports
  5. Run TCP/UDP servers
  6. Run IP/TCP/UDP clients
  7. Access files of mounted media (e.g. an USB stick)
  8. Retrieve status information from the system
  9. Get or set configuration parameters
  10. Write to syslog
  11. Transfer files over HTTP/FTP
  12. Get system events / Reboot system
  13. Control the LEDs

The SDK API which can be obtained from the NetModule support page provides an overview but also explains all functions in detail.

Please note that some functions require the corresponding services (e.g. E-Mail, SMS) to be properly configured prior to utilizing them in the SDK. Let us now pay some attention to the very powerful API function nb_status. It can be used to query the router’s status values in the same manner as they can be shown with the CLI. It returns a structure of variables for a specific section (a list of available sections can be obtained by running cli status -h).

By using the dump function you can figure out the content of the returned structure:

/* dump current location */
dump ( nb_status (" location "));

The script will then generate lines like maybe these:

struct(8): {
.LOCATION_STREET = string[11]: "Bahnhofquai"
.LOCATION_CITY = string[10]: "Zurich"
.LOCATION_COUNTRY_CODE = string[2]: "ch"
.LOCATION_COUNTRY = string[11]: "Switzerland"
.LOCATION_POSTCODE = string[4]: "8001"
.LOCATION_STATE = string[6]: "Zurich"
.LOCATION_LATITUDE = string[9]: "47.3778058"
.LOCATION_LONGITUDE = string[8]: "8.5412757"
}

In combination with the nb_config_set function, it is possible to start a re-configuration of any parts of the system upon status changes. Here is an example how one might adopt those functions:

/* check current city and enable the second WAN link */
location = nb_status (" location ");
if ( location ) {
city = struct_get ( location , " LOCATION_CITY ");
if ( city == " Wonderland ") {
for (led = 0; led < 5; led ++) {
nb_led_set (led , LED_BLINK_FAST | LED_COLOR_RED );
}
} else {
printf ("You 'll never walk alone in %s ...\ n", city );
nb_config_set (" wanlink .1. mode =1");
}
}

Running SDK

In the SDK, we are speaking of scripts and triggers which form jobs. Any arena script can be uploaded to the router or imported by using dedicated user configuration packages. You may also edit the script directly at the Web Manager or select one of our examples. You will further have a testing section on the router which can be used to check your syntax or doing test runs. Once uploaded, you will have to specify a trigger, that is, telling the router when the script is to be executed. This can be either time-based (e.g. each Monday) or triggered by one of the pre-defined system events (e.g. wan-up). With both, a script and a trigger, you can finally set up an SDK job now. The test event usually serves as a good facility to check whether your job is doing well. The admin section also offers facilities to troubleshoot any issues and control running jobs. The SDK host (sdkhost) corresponds to the daemon managing the scripts and their operations and thus avoiding any harm to the system. In terms of resources, it will limit CPU and memory for running scripts and also provide a pre-defined portion of the available flash storage. You may, however, extend it by external USB storage or (depending on your model) SD cards. Files written to /tmp will be hold in memory and will be cleared upon a restart of the script. As your scripts operate in the sandbox, you will have no access to tools on the system (such as ifconfig).

SDK Samples

Built-in Scripts

ScriptDescription
best-operator.are This script will scan for operators on startup and choose the one with the best signal
candump.are This script can be used to receive CAN messages
config-summary.are This script shows a summary of the currently running configuration.
dio-monitor.are This script monitors the DIO ports and sends a SMS to the specified phone number.
dio-server.are This script implements a TCP server which can be used to control the DIO ports.
dio.are This script can be used to set a digital output port.
dynamic-operator.are This script will scan Mobile2 and dial the appropriate SIM on Mobile1
email-to-sms.are This script implements a lightweight SMTP server which is able to receive mail and forward them as SMS to a phone number.
etherwake.are This script can be used to wake up a sleeping host (WakeOnLan)
gps-monitor.are A script for activating WLAN as soon as GPS position (lat,lon) is within a specified range.
gps-udp-client.are This script sends the local GPS NMEA stream to a remote UDP server.
gps-upd-client-compat.are This script sends the local GPS NMEA stream to a remote UDP server (incl. device identity).
led.are This script can be used to set a LED
mount-media.are This script can be used to mount an USB storage stick.
ping-supervision.are This script will supervise a specified host.
read-config.are This script can be used to read a configuration parameter.
remote-mail.are This script reads and sends mails from a remote IMAP/POP3/SMTP server
scan-mobile.are This script can be used to switch the Mobile LAI according to available networks
scan-wlan.are This script can be used to switch the WLAN client network according to availability
send-mail.are This script will send an E-Mail to the specified address.
send-sms.are This script will send an SMS to the specified phone number.
serial-read.are This script can be used to read messages from the serial port.
serial-readwrite.are This script will write to and read from the serial port.
serial-tcsetattr.are This script can be used to set/get the attributes of the serial port.
serial-udp-server.are This script reads messages coming from the serial port and forwards them via UDP to a remote host (and vice versa).
serial-write.are This script can be used to write a message to the serial port.
sms-control.are This script will execute commands received by SMS.
sms-delete-inbox.are This script can be used to flush the SMS inbox.
sms-read-inbox.are This script can be used to read the SMS inbox.
sms-to-email.are This script will forward incoming SMS messages to a given E-mail address.
sms-to-serial.are This script can be used to write a received SMS to the serial port.
snmp-agent.are This script extends MIB entries of the SNMP agent
snmp-cmd.are This script issues SNMP set/get commands
snmp-trap.are This script can be used to send SNMP traps
status.are This script can be used to display all status variables
syslog.are Throw a simple syslog message.
tcpclient.are This script sends a message to a TCP server.
tcpserver.are This script implements a TCP server which is able to receive messages.
techsupport.are This transfers a techsupport to a remote FTP server
transfer.are This scripts stores the latest GNSS positions in a remote FTP file
udp-msg-server.are This script will run an UDP server which is able to receive messages and forward them as SMS/E-Mail.
udpclient.are This script sends a message to a remote UDP server.
udpserver.are This script implements an UDP server which is able to receive messages.
update-config.are This script can be used to perform a configuration update
voice-dispatcher-audio.are This script implements an audio voice dispatcher
webpage.are This script will generate a page which can be viewed in the Web Manager
write-config.are This script can be used to set a configuration parameter.