Configuration provisioning of the SolidSense gateways

Please Note

The documentation for SolidSense software is not maintained by SolidRun and the information herein is not actual with the latest version of the software, please contact our partner SolidSense Connect who is now developing the SolidSense software.
Here is the Solidsense-Connect WiKi documentation page.

The documentation for SolidSense software is not maintained by SolidRun and the information herein is not actual with the latest version of the software, please contact our partner SolidSense Connect who is now developing the SolidSense software.

Introduction

Configuring the gateway with the customized configuration can become a burden if many gateways have to be configured. To address this problem a provisioning service has been develop and allow to define any configuration from a YAML definition file. There is a generic minimum configuration part of the factory (read-only) image that allows a basic start of the system allowing further configurations via Kura. On top, a custom configuration can be defined that will override and/or augment the basic configuration to create the operational configuration needed for the application. With that service we can have gateways that start and go into service without any on site provisioning activities.

The SolidSense provisioning is taking Yaml files as input (factory basic configuration + custom configuration) and generates the key system configuration files:

Kura configurations files and mainly the snapshot_0.xml
WiFi configuration files
ppp configuration files
SolidSense configuration files

Having your SolidSense provisioning file allows to commission all your gateways without any manual entry so with efficiency and reliability.

Factory configuration (read-only)

The factory configuration includes 2 files that shall be located in /opt/SolidSense/config

SolidSense-conf-base.yml => Generic standard configuration
SolidSense-HW-configurations => Definition of HW configuration description

The provisioning process also make use of files located in /opt/SolidSense/template

Default configuration

Network:
Ethernet (eth0): WAN DHCP client
WiFi (wlan0) : LAN Access Point (WPA2) DHCP Server SSID=Serial Number
Cellular (ppp0) : Not configured

Services:
MQTT Client for Kura: enabled
modem_gps: enabled if the modem is present

Defining a custom startup configuration

Here are some examples that can be pasted into your own SolidSense-conf-custom.yml file. And an example file that includes Wirepas parameters and ppp SolidSense-conf-custom.yml

Structure of the Yaml configuration file

The file includes two main sections:

The ‘gateway’ section in which global variables can be defined

gateway:

    snapshot_0: snapshot_0.xml #this is the template snapshot do not change it unless full test
    #
    # set of global variables (for convenience and example)
    #
    MQTT_BROKER: YOUR_MQTT_URL
    MQTT_PORT: 1883
    MQTT_USER: YOUR_USER
    MQTT_PASSWORD: YOUR_PASSWORD

The ‘services’ section that is a list of ‘service’ that have the following structure

- service:
    type: WirepasSink
    name: sink1
    state: active
    parameters:
        configuration: WirepasSinkConfigurationService
        plugin: WirepasConfigurationService.dp
        plugin_name: WirepasConfigurationService
        system: wirepasSink1
        port: ttymxc1 # physical port
        start: true

    variables:
        NETWORK_ID: $WP_TEST_ID
        NETWORK_CHANNEL: $WP_TEST_CHANNEL
        ADDRESS: $UNIQUE_ADDRESS0
    properties:
        sinkAddress: $ADDRESS
        networkChannel: $NETWORK_CHANNEL
        networkAddress: $NETWORK_ID
        sinkName: $service_name

Services definition

Each ‘service’ has the following possible parameters

‘type’: the service class as defined by the SolidSense provisioning system
‘name’: the internal name of the service. For network interfaces it shall be identical to the device name
‘state’: the state of the service after provisioning
# disabled the service will not be configured and and started # auto the service is configured but the start and activation is done by another process or context dependant # interactive the service configuration is to be done via Kura # active the service is configured and activared during provisioning
‘override’: If true, then the existing default configuration is ignored and the service is refined from scratch, if false then all existing configuration is kept and only the parameters specified in the file are modified.
‘parameters’. This is a set of values that are used to configure the service.
‘variables’. List of local variable definitions
‘properties’: This is the list of the Kura properties that are set during the provisioning stage and written in the snapshot_0.xml file. Only modified or additional properties needs to be defined in the file otherwise default values from the baseline snapshot_0.xml file are used.

Among parameters some a class specific but some others are generic, in particular for all services from the KuraService class and subclasses.

‘configuration’ : Name of the ‘configuration’ XML block in Snapshot_0 file. It can be prefixed by “org.eclipse.kura.<service>.” This prefix is to be ignored.
‘plugin’ : when the service requires a dynamic plugin add-on in Kura, this is the file name of the compiled dp. (shall be in: /opt/eclipse/kura/packages). Versions suffix are not taken into account.
‘plugin_name’ : As a dynamic plugin file can include several services, this is the name of the class (in Java) associated with the service
‘prefix’ : this is the prefix used for properties. If no prefix is defined, then the full property name is to be explicitly given for the property
‘system’: systemd service associated with the service

SolidSense provisioning classes hierarchy

Example 1: cellular as WAN and Ethernet as LAN

To be edited:

Cellular connection parameters: APN
Kapua connection parameters

Example 2: Starting the SolidSense MQTT service automatically

Applying the custom configuration

Step 1: copy the YAML configuration on the gateway in the directory /data/solidsense/config/SolidSense-conf-custom.yml. Note that this is not affected by software upgrade or factory reset.

Step 2: restart the gateway with a factory reset. As a new configuration is applied, it shall be understood that any previous configuration will be lost. All content of the /data partition is left untouched.

Restart command. This command can be applied from a local shell (ssh) or from Kapua.

At that point the overlay file system is wiped out and the system reboots. Then the provision configuration is applied.