Netcomm

Overview

The following sections demonstrate how to use a NetComm router with Cumulocity. It describes how to

The following sections assume that the router has the NetComm agent package installed. The agent is compatible with the NTC-6200 and NTC-140W. For more information on a particular feature of the router, please consult the respective manual found in the “Downloads” section of the router’s home page.

Configuring the router

The support for Cumulocity can be configured through the router’s web user interface. To do so, login to the user interface as described in the router’s manual. Navigate to the “System” tab and click on the “Internet of Things” menu item.

Cumulocity configuration

Verify that the toggle switch “Cumulocity agent” is set to “ON” and the URL shown in “Server” points to the Cumulocity instance that you want to connect. For example, use

Optionally, you can activate data collecting for the following functionalities:

All these options are disabled by default (the interval is set to 0).

The web interface also shows the status of the connection to Cumulocity:

(For version 2.x)

(For version 3.x onwards) * Checking network connection: waiting for mobile network connection at boot. * Bootstrapping: load credentials or request credentials from Cumulocity. * Integrating: Connecting to Cumulocity. * Loading plugins: loading Lua plugins. * Connected: The agent is successfully connected to Cumulocity. * No server URL: no or invalid server URL. * Bootstrap failed: Can not get credentials from Cumulocity. * Integration failed: can not connect to Cumulocity. * Create threads failed: not able to start reporter or device push.

Connecting the router

To register your NetComm router to Cumulocity, you need the router’s serial number as Device ID. The registration process is described in section “Connecting devices” in the User Guide. The serial number is printed on the back side of the router as shown below. Alternately, it is also available in the router’s web user interface. Navigate to “System”, “Internet of Things” and view the “Device ID” field.

Users of version 2.x or upgrading from 2.x to 3.x should use the router’s MAC address. Please make sure to use only lowercase letters and numbers when entering the MAC address. Do not use colons to separate the MAC address. For example, the MAC address from the picture would be entered as

006064dda4ae

MAC address

After clicking the “accept” button, navigate to “All devices”, the router should appear here after registration. The default name of a router is “<model> (S/N <serial number>)“, where <model> is the device model name. For example, the above router would appear as “NTC-6200-02 (S/N 165711141901036)”. Click on the router to view the detailed information and to access the functionality described in the remaining sections of this document. In order to distinguish a registered router from other devices in the listing, you can change the router’s name on the “Info” tab, which also displays basic information such as serial number of the router and SIM card data. After changing the name, remember to click “save changes” button at the bottom of the “Info” page.

Device details

Configuring network parameters

You can view and configure the essential mobile network (“WAN”) and local area network (“LAN”) parameters in the “Network” tab as shown in the screenshot below.

The mobile network (“WAN”) parameters shown in the user interface correspond to the first profile stored in the router. These parameters can be remotely configured directly or via SMS.

For SMS configuring, the router needs to be configured to accept SMS commands. Consult the router’s manual on the relevant parameters for SMS configuration, or use the router’s web user interface. You also need to have an SMS gateway configured with your account. Contact support for setting up an SMS gateway. For more information on Device Shell, consult the user’s guide.

Note configuring WAN parameters via both IP and SMS mode requires Cumulocity 7.26. When you configure a wrong APN setting, the device will lose mobile network connection and can only be managed by limited SMS functionality.

WAN parameters

LAN and DHCP parameters can be directly configured from Cumulocity as well.

LAN parameters

Managing software and firmware

The installed software and firmware on the router can be remotely managed using the standard software and firmware management feature from Cumulocity, as described in the Device management user’s guide.

Software packages need to be in ipkg format and follow the naming convention “<package>_<version>_<arch>.ipk”. Version numbers including letters are not supported. All package management methods (install, upgrade, downgrade, removal) are supported through the router’s package manager. If software packages have dependencies, please make sure to install these first.

The package “smartrest-agent_<version>_arm.ipk” represents the NetComm agent. It is prohibited to remove this package from Cumulocity.

When upgrading from versions older than 2.1.1, the device needs to be re-registered.

Firmware can be uploaded and installed on the router as well. To successfully upgrade the firmware, make sure that the target firmware includes the agent package. If the agent package is not included in the target firmware, the agent will not start after the installation. Firmware files need to follow Netcomm’s naming convention (”<name>_<version>.cdi”).

Software/firmware

Monitoring system resources

You can record statistics of the router’s system resources usage for troubleshooting purposes. The following statistics are available:

By default, collection of resource statistics is disabled. They can be enabled by setting a non-zero collecting interval in the “System resources measurements” entry of the router user interface or using Device Shell:

set service.cumulocity.system_resources.interval=<interval>

Collected data can be accessed in the “Measurements” tab or in a dashboard.

Using GPS

To locate or trace the router, connect a GPS antenna to the router and enable its GPS functionality. Then configure the frequency of data collection by setting the “GPS position interval” and/or the “GPS position event” to a non-zero value. “GPS position interval” defines how often the current location of the router is updated. “GPS position event” defines how often the current location is stored as location update event for tracing. Similarly, you can set these parameters from Device Shell:

set service.cumulocity.gps.update_interval=<update interval>
set service.cumulocity.gps.interval=<event interval>

After you applied the configuration changes, wait a moment for the first GPS data to arrive, then refresh the page. A “Location” and a “Tracking” tab should now appear. See the “Location” and “Tracking” sections in the user guide for more information.

Using GPIO

The following GPIO functionalities are supported:

Consult the documentation of your router for more information about its specific IO settings. The available functionalities may vary between different device models. For example, the NTC 6200 model supports GPIO pins 1-3, while the NTC 140W model supports only GPIO pin 1.

Analog input

To regularly poll the input voltage of a GPIO pin and send it to Cumulocity, set “GPIO analog measurements” to a non-zero value. Alternatively, use Device Shell:

set service.cumulocity.gpio.interval=<interval>
set service.cumulocity.gpio.<port>.notify=measurement

<port> is the numbering of the GPIO pin. For the NTC-6200, <port> can be 1, 2 or 3, while for NTC-140W, <port> can only be 1. The Visualized result is then visible in “Measurements”.

Digital input

You can raise alarms from digital inputs. These can be configured using the router user interface or through Device Shell. The format is

set service.cumulocity.gpio.<port>.notify=alarm
set service.cumulocity.gpio.<port>.debounce.interval=<SECONDS>
set service.cumulocity.gpio.<port>.alarm.text=<ALARM_TEXT>
set service.cumulocity.gpio.<port>.alarm.severity=<severity>

Possible values for the notify parameter are:

The debounce interval reduces electrical noise from the GPIO inputs: The shorter the interval, the noisier the value but the faster the reaction to signal changes. The default debounce interval is 10 mins.

You can override the default alarm text by setting the “text” property. By default, this value is empty and “gpio<N> is active” is used as text, where <N> is the numbering of a GPIO pin.

Valid alarm severities are:

The inputs are checked every second for changes.

Digital output

Digital outputs can be controlled using the “Relay array” plugin, see below in the screenshot. The numbering of the GPIO pins are the same as listed on the router. For the NTC-6200 model, three GPIO pins can be set, while for the NTC-140W model, only the first pin has effect.

Relay Array

Configuration Management

You can retrieve, modify and save user configuration data. To do this, navigate to the “Configuration” tab of the router, click on the “Reload” button in the “CONFIGURATION” widget to request configuration data. It will take a few seconds to download. After the configuration data has arrived, you will see a list of parameters and their corresponding values. You can then make changes to the configuration and save them back to the device.

You can also request a configuration snapshot from the device and later apply the configuration snapshot to other devices.

Starting from agent version 3.1.1 and Cumulocity version 7.26 there is also RDB snapshot support, which is a super-set of the configurations. This is mainly for troubleshooting purpose.

RDB setup

Prior to Cumulocity 6.9, this widget was in the “Control” tab. Starting from Cumulocity 6.9, you can also take entire configuration snapshots including the non-textual parts of the device and send reference configuration snapshots back to the device.

Configuring devices to use SMS mode

To use SMS commands for devices, open the router’s web interface and navigate to “Services”, “SMS messaging”, then “Diagnostics”. Configure the device as follows:

Enable SMS mode

For more information please refer to “Control devices via SMS”.

Device Shell

With Device Shell, you can read and write individual configuration parameters from the device, as well as execute diagnostic commands. For more information, please refer to the user guide. Consult the Netcomm documentation for valid parameters and diagnostic commands. The general format is:

Multiple get, set and execute commands can be sent using a semicolon as separator. Click the “Get Predefined” link to access frequently used parameters and commands.

Device Shell

Event notifications

The router reports certain system events as notifications, which can be forwarded to Cumulocity as alarms. The system events help, for example, in troubleshooting mobile network issues. For more information on the different types of events and how to forward them, please consult the Netcomm documentation (for example, Section “Event notification” in the user’s guide). To forward an event as alarm, set up a UDP destination sending to Port 1331 on localhost (Section “Destination configuration”).

Event notifications

Cloud Fieldbus

You can connect Modbus-TCP and Modbus-RTU slaves to the router via LAN and serial port, respectively, and manage them remotely in Cumulocity. To do so, you need to

For Modbus-TCP setup:

For Modbus-RTU setup:

where <mode> can be rs232, rs422 or rs485. You may need to reboot the device after changing the mode.

The default serial port /dev/ttyAPP4 should work with no further configuration. In case it’s empty or you need to configure a different port, it can be configured in the Cumulocity menu in devices’ web UI, see “Configuring the router”.

Some USB to serial adapters have echo mode enabled by default, this can render the Modbus communication stop working completely. If you have one of these adapters, consult the adapter’s manufacturer about how to disable it.

Model NTC-140W doesn’t support modbus RTU, so you will not see the corresponding functionality in the UI.

Model NTC-140W doesn’t support modbus RTU, so you will not see the corresponding functionality in the UI.

Then:

Log viewer

You can download and view logs from the device. Log files can be quite big, you can set filtering criteria to get only what is interesting for you.

From right you can set date range (date from and date to), you can select log file. Next you can search the text, and only matching lines are retrieved from the device. You can also limit matched lines.

Received logs are visible in a list below. You can click on it to show log file content at the bottom of the page. Last requested log is opened automatically.

Log viewer

VNC remote access

If you have a device which supports VNC, Telnet or SHH remote access, it’s now possible to manage your device via Cumulocity starting from Agent v4.2.0.

As shown in the screenshot, you can add your VNC, Telnet or SSH servers as an endpoint with appropriate IP and port in the Remote Access tab of a particular device in the Device Management application. If you click Connect, the display content of your remote server will be shown in a new browser window.

Info: The “vncproxy” package is required and must be installed.

VNC

MQTT

Starting from v4.0.0, agent added supported for MQTT protocol. In case you want to upgrade from previous 2.x or 3.x versions, no additional configurations are required for enabling MQTT. However, in case you need to manually configure MQTT enablement, run following command via “Device Shell”:

set service.cumulocity.mqtt.enable = <0|1>

to either disable or enable MQTT communication. The configured server URL remains the same. For example, http://demos.cumulocity.com if you want to use plain MQTT, or https://demos.cumulocity.com if you want secure MQTT + TLS.

Server URL http://developer.cumulocity.com will not work with MQTT since it points one different instance which doesn’t have MQTT enabled. You should use http://demos.cumulocity.com instead.

To configure the MQTT keepalive interval (default to 240 seconds):

set service.cumulocity.mqtt.keepalive = <seconds>

to change the keepalive interval.

Changing keepalive interval only has affect after the next reboot.

Netcomm Agent Developer's Guide

Index:

Configuration

Credentials

Credentials are stored in RDB in values: * service.cumulocity.connection.username – with tenant, for e.g. management/device_006064ce80bf * service.cumulocity.connection.password – mangled password

Password format is: * *1* – prefix * mangle process: - password, if is smaller that 16 character it’s filled up to 16 bytes from string fN4\033q8!7n\n13Q$8f - xor’ed with string \x21\x63\x0e\x30\x2f\x1b\x9a\xc2\x34\x55\xe8\x7d\x32\xda\x30\xea\x59 - base64 * *– suffix

Event notifications

Cumulocity alarms are base on NetComm UDP events described in NetComm Wireless M2M Device Model (ver.1.3). The agent use definitions from file /usr/local/etc/udp_alarms.ini. There are: * general section [alarm] * per event sections [alarm.N], where N is event number (from M2M Device Model)

Alarm section contains severity value, default is MAJOR. You can overwrite it.

Each event section contains: * event number in section name * name – alarm name, defined in M2M Device Model, used also as notification type * severity – overwrites default severity, optional, default: non exists * type – Cumulocity notification type, overwrites names, optional, default: non exists

Text from UDP event is directly set as notification in Cumulocity.

Log viewer

Log viewer plug-in (lua__logs) uses definitions from file /usr/local/etc/logs.ini. There are list of supported logs in global value logs:

logs = logread, dmesg, sragent

This is names of logs declared in Cumulocity and list of sections with log details.

Each section contains: * file or execute – log source, when execute is used, log is got from standard output * pattern – line parse pattern in Lua RegEx syntax (tutorial) * fields – names of parsed fields in RegEx sub-patterns, if name is used more that one time sub-patterns are joined with space separator * timeFormat – time format used in this log: - strptime format, - $(uptime) – time offset form system start (useful for dmesg)

Example: [syslog] file = /var/log/syslog pattern = (%a+ +%d+ +%d+:%d+:%d+)%s+%S+%s+(%S+):%s(.)%s*$ fields = time, module, text timeFormat = %B %d %T

[logread]
execute = logread
pattern = (%a+ +%d+ +%d+:%d+:%d+)%s+%S+%s+(%S+)%s+(%S+):%s*(.*)%s*$
fields = time, level, module, text
timeFormat = %B %d %T

Netcomm Release Notes

Release notes for NetComm Agent 4.0

This document describes the Cumulocity agent package for the NetComm Wireless NTC-6200 and the NetComm Wireless NTC-140W router.

Supported functionality

The agent supports the following functionality:

Known limitations and bugs

System requirements

The agent was tested on an NTC-6200 device with firmware version 2.0.36.10. For remote configuration of WAN parameters, you need a SIM card with SMS function. Currently, GSMA OneAPI (e.g., on Ericsson DCP), OpenIT and Jasper Wireless are supported APIs for SMS providers. Please contact support for connecting to an SMS provider.

Agent version 3.2.0 and up require backend minimum version 7.20 for multip-XID support.

Agent versions 2.3 and up require Cloud Fieldbus 4. They are not compatible with earlier versions of the Cloud Fieldbus application.

Agent versions 2.1.10 and up require at least Cumulocity 6.10 to support the new log viewer.

Installing the agent

The agent will automatically start after installation and the router can then be registered with Cumulocity. Subsequent upgrades or downgrades can be performed remotely via the agent’s software management feature, or locally via the router’s web portal.

When upgrading from versions older than 2.1.1, the device needs to be re-registered.

Using the agent

For information on using the agent, please visit the NetComm Agent User’s Guide.

History

4.2.3

Agent Software, CA certificate bundle, VNC Proxy. Changes:

4.0.2

Agent Software, CA certificate bundle, VNC Proxy. Changes:

4.0.1

Agent Software, CA certificate bundle, VNC Proxy. Changes:

4.0.0

Agent Software, CA certificate bundle, VNC Proxy. Changes:

3.2.2

Download link. Changes:

3.2.0

Download link. Changes:

3.1.6

Download link. Changes:

3.1.2

Download link. Changes:

3.0.0

Download link. Changes:

2.3.6

Download link. Changes:

2.3.5

Download link. Changes:

2.2.6

Download link. Changes:

2.1.10

Download link. Changes:

2.1.8

Download link. Changes:

2.1.6

Download link. Changes:

2.1.4

Download link. Changes: