Efento NB-IoT sensors – CoAP loader integration

Efento CoAP loader

We have created a CoAP loader application which sets up a CoAP server on a machine, handles the communication with sensors and forwards the data over REST API to the selected endpoint.

In order to set up the application:

1. Download Efento CoAP loader using this link
2. Modify the settings in application.yml file, to match your setup:
   1. Endpoint – address of the REST endpoint where you want receive measurements from the CoAP loader
   2. appPort – coap loader application running port
   3. coapPort – port on which the CoAP loader listens to the messages from the sensors
3. Run the application on the machine (go to the folder where the files are saved and type java -jar coapgateway.jar). Make sure that the machine on which the CoAP loader is running either has a public IP address or (if it is behind the NAT) has the CoAP port forwarded on the router.
4. In the main directory (where the .jar file is located) a log file (log.log) will be created
5. Configure the sensor to send the data to the server, on which the CoAP loader is running
   1. Download the app from Google Play, and select “Nearby devices” mode
   2. Enable “Power user mode” – open the application menu (menu icon in the upper left corner) and quickly tap 10 times on Efento Logo
   3. Wait for few seconds for the application to find the sensor over BLE interface
   4. Connect to the sensor and from the configuration menu (three dots in the upper right corner) choose “Server configuration”-> „Other”
   5. Enter the IP address of the server, on which the CoAP loader is running and the port number on which the machine is listening to CoAP packets
   6. Optionally, you can also change the transmission and measurement intervals
   7. Once the sensor sends the data to the server, you will see it in the command line
6. CoAP loader will forward all the measurements over the REST API to the endpoint you set in the first step of the configuration. Make sure that your application response contains response status code 2xx (eg. 201, 204, 205).

REST communication CoAP Loader -> User’s platform

{

  "measurements" : [

  {

    "serial" : [string], // serial number of the sensor

    "response_handle":[number], // sensor number in response (optional)

    "battery" : [string], // battery level: ok/low

    "signal" : [number], // signal quality indicator based on RSSI. Values described below

    "measured_at" : [string], // UTC date

    "measurement_interval" : [number], // measurement interval in seconds

    "next_measurement_at" : [string], // next connection date

    "params" : [

      {

        "channel" : [number], // sensor channel number: 1/2/3

        "type" : [string], //  temperature/humidity/pressure/pressure_diff/open-close

        "value" : [string]

      }

    ]

  }

  ]

}

Example:

{

  "measurements" : [

  {

    "serial" : "282C024FFFB1",

    "response_handle": 1,

    "battery" : "ok",

    "signal" : 13,

    "measured_at" : "2018-10-12 15:28:21",

    "measurement_interval" : 180,

    "next_measurement_at" : "2018-10-12 18:28:21",

    "params" : [

      { "channel" : 1, "type" : "temperature", "value" : 6 }

    ]

  },

  {

    "serial" : "282C024FFFB2",

    "response_handle": 2,

    "battery" : "ok",

    "signal" : 21,

    "measured_at" : "2018-10-12 15:28:21",

    "measurement_interval" : 180,

    "next_measurement_at" : "2018-10-12 18:58:21",

    "params" : [

      { "channel" : 1, "type" : "temperature", "value" : 12},

      { "channel" : 2, "type" : "humidity", "value" : 51}

    ]

  },

  {

    "serial" : "282C024FFFB3",

    "response_handle": 3,

    "battery" : "ok",

    "signal" : 3,

    "measured_at" : "2018-10-12 15:28:21",

    "measurement_interval" : 180,

    "next_measurement_at" : "2018-10-12 20:28:21",

    "params" : [

      { "channel" : 1, "type" : "temperature", "value" : 50},

      { "channel" : 2, "type" : "humidity", "value" : 30},

      { "channel" : 3, "type" : "pressure_diff", "value" : 21 }

     ]

  },

  {

    "serial" : "282C024FFFB4",

    "response_handle": 4,

    "battery" : "ok",

    "signal" : 7,

    "measured_at" : "2018-10-12 15:28:21",

    "measurement_interval" : 180,

    "next_measurement_at" : "2018-10-12 16:28:21",

    "params" : [
 
      { "channel" : 1, "type" : "open-close", "value" : 0},

      { "channel" : 2, "type" : "open-close", "value" : 1},

      { "channel" : 3, "type" : "open-close", "value" : 1}

    ]

  }

 ]

}

Signal quality indicator returns values based on the RSSI

Changing sensor’s settings

Efento CoAP loader can be used to remotely change the sensor’s settings. To change the sensor’s settings, your application has to send a new configuration to the CoAP loader in the response body. All the sensor settings are described in the “Efento NB-IoT sensor User manual”, which can be found at getefento.com/support

REST communication User’s platform -> CoAP Loader

{

  "measurementPeriodBase":180,

  "measurementPeriodFactor":14,

  "transmissionInterval":10800,

  "ackInterval":1000,

  "ackIntervalMode":"VALUE",

  "bleTurnoffTimeout":3600,

  "bleTurnoffTimeoutMode":"VALUE",

  "requestDeviceInfo":false,

  "requestFirmwareUpdate":false,

  "disabledSendingConfig":false,

  "transferLimit":10,

  "transferLimitMode":"VALUE",

  "transferLimitTimer":1500,

  "transferLimitTimerMode":"VALUE",

  "serverDataIp":"52.22.22.22",

  "serverDataPort":5683,

  "apn":"nbiot.com",

  "apnMode":"VALUE",

  "plmn":123456,

  "plmnMode":"VALUE",

  "serverUpdateIp":"52.22.22.22",

  "serverUpdatePortCoap":5683,

  "serverUpdatePortUdp":50000,

  "detachRequest":100,

  "acceptWithoutTesting":true,

  "cloudToken":"c96f98ce-bccf-4413-8ac3-77dfd33cd07c",

  "cloudTokenConfig":"CLOUD_TOKEN_VALUE",

  "supervisionPeriod":100,

  "supervisionPeriodMode":"VALUE",

  "requestMemoryReset":false,

  "bands":[

    0

  ],

  "alarmRules":[

    {

      "sensorSideId":0,

      "slotNumbers":[

        0

      ],

    "condition":"HIGH_THRESHOLD",

    "alarmRuleType":"TEMPERATURE",

    "threshold":8,

    "hysteresis":0.5,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 5

    }

  ]

}

Parameters values

Parameters sent in the response body (JSON) can have the following values:

measurementPeriodBase // number, 1 - 36000

measurementPeriodFactor // number, 1 – 100

transmissionInterval // number, 60 – 604800

ackInterval // number, 1 – 2592000

ackIntervalMode, // enum (string): “NOT_SEND”, “VALUE”,

“ALWAYS_ACK”, “NEVER_ACK”

bleTurnoffTimeout // number, 60 – 604800

bleTurnoffTimeoutMode // enum (string): “NOT_SEND”, “VALUE”,

“ALWAYS_ON”

requestDeviceInfo // boolean, true or false

requestFirmwareUpdate // boolean, true or false

transferLimit // number, 1 – 65534

transferLimitMode // enum (string): “NOT_SEND”

“VALUE”

“DISABLE”

transferLimitTimer // number, 1 – 65534

transferLimitTimerMode // enum (string): “NOT_SEND”

“VALUE”

“DISABLE”

serverDataIp // string, correct ip address format NNN.NNN.NNN.NNN

serverDataPort // number, 1 – 65535

apn // string, length: 1 – 49

apnMode // enum (string): “NOT_SEND”

“VALUE”

“AUTO”

plmn // number, 10000 – 999999

plmnMode // enum (string): “NOT_SEND”

“VALUE”

“AUTO”

serverUpdateIp // string, correct ip address format NNN.NNN.NNN.NNN

serverUpdatePortCoap // number, 1 – 65534

serverUpdatePortUdp // number, 1 – 65534

detachRequest // number, 1 – 604800

acceptWithoutTesting // boolean, true or false

cloudToken // string, value: c96f98ce-bccf-4413-8ac3-77dfd33cd07c

cloudTokenConfig // enum (string): “CLOUD_TOKEN_VALUE”

“CLOUD_TOKEN_IMEI”

“CLOUD_TOKEN_SENDING_DISABLED”

supervisionPeriod // number, 180 – 5184000

supervisionPeriodMode // enum (string): “NOT_SEND”

“VALUE”

“DISABLE”

requestMemoryReset // boolean, true or false

bands // array of integers, possible values: 1, 2, 3, 4, 5, 6, 8, 12, 13,

17, 18, 19, 20, 25, 26, 28, 66, 71, 85

alarmRules // array of object (alarmRule), param of single alarm rule

// described below

ALARM RULE PARAMETERS

slotNumbers // array of integers, possible values: 0 – 5

condition // enum (string), non-null, values:

“DISABLED”

“HIGH_THRESHOLD”

“LOW_THRESHOLD”

“DIFF_THRESHOLD”

“BINARY_CHANGE_STATE”

alarmRuleType // enum (string): “TEMPERATURE”

“HUMIDITY”

“ATMOSPHERIC_PRESSURE”,

“DIFFERENTIAL_PRESSURE”,

“PULSE_CNT”,

“ELECTRICITY_METER”,

“WATER_METER”

threshold // number

hysteresis // number

averageMode // enum (string): “MOVING_AVERAGE”

“WINDOW_MODE”

averageNumberOfSamples // number, 1 – 10

Param sets depend on the non-null condition param!

• DISABLED

• • other fields set null (slotNumbers, alarmRuleType, threshold, hysteresis, averageMode, averageNumberOfSamples)

• HIGH_THRESHOLD and LOW_THRESHOLD

• • set slotNumbers
  • set alarmRuleType
  • set threshold
  • set hysteresis
  • set averageMode
  • set averageNumberOfSamples

• DIFF THRESHOLD

• • set slotNumbers
  • set alarmRuleType
  • set threshold
  • set averageMode
  • set averageNumberOfSamples
  • other fields set null (hysteresis)

• BINARY_CHANGE_STATE

• • set slotNumbers
  • other fields set null (alarmRuleType, threshold, hysteresis, averageMode, averageNumberOfSamples)

Range and resolution of the threshold param depend on the alarmRuleType param!

• TEMPERATURE

• range: -273.2 – 4000.0

• • • resolution: 0.1

• HUMIDITY

• range: 0 – 100

• resolution: 1

• ATMOSPHERIC_PRESSURE

• range: 1.0 – 2000.0

• • • resolution: 0.1

• DIFFERENTIAL_PRESSURE

• range: -10000.0 – 10000.0

• • • resolution: 1

• PULSE_CNT

• range: 0 – 8000000

• resolution: 1

• ELECTRICITY_METER

• range: 0 – 8000000

• • • resolution: 1

• WATER_METER

• range: 0 – 8000000

• resolution: 1

Range and resolution of the hysteresis param depend on the alarmRuleType param!

• TEMPERATURE

• range: 0 – 4273.2

• • • resolution: 0.1

• HUMIDITY

• range: 0 – 100

• resolution: 1

• ATMOSPHERIC_PRESSURE

• range: 0 – 1999.0

• • • resolution: 0.1

• DIFFERENTIAL_PRESSURE

• range: 0 – 20000.0

• • • resolution: 1

• PULSE_CNT

• range: 0 – 8000000

• resolution: 1

• ELECTRICITY_METER

• range: 0 – 8000000

• • • resolution: 1

• WATER_METER

• range: 0 – 8000000

• resolution: 1

Examples

{

  "measurementPeriodBase":300,

  "measurementPeriodFactor":1,

  "transmissionInterval":3600

}

{

  "apn":"nbiot.com",

  "apnMode":"VALUE"

}

{

  "serverDataIp":"45.45.45.45",

  "serverDataPort":1212,

    "cloudTokenConfig":"CLOUD_TOKEN_IMEI"

}

{

  "alarmRules":[

  {

    "slotNumbers":[

      0

    ],

    "condition":"HIGH_THRESHOLD",

    "alarmRuleType":"TEMPERATURE",

    "threshold":5,

    "hysteresis":0,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 1

  },

  {

    "slotNumbers":[

      1

    ],

    "condition":"LOW_THRESHOLD",

    "alarmRuleType":"HUMIDITY",

    "threshold":50,

    "hysteresis":0,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 1

  },

  {

    "slotNumbers":[

      0

    ],

    "condition":"DIFF_THRESHOLD",

    "alarmRuleType":"TEMPERATURE",

    "threshold":0.5,

    "hysteresis":0,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 1

    }

 ]

}

{

  "alarmRules":[

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "slotNumbers":[

      0

    ],

    "condition":"HIGH_THRESHOLD",

    "alarmRuleType":"TEMPERATURE",

    "threshold":5,

    "hysteresis":0,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 1

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  },

  {

    "condition":"DISABLED"

  }

  ]

}

Troubleshooting

Issue: Server does not receive the data from the sensor

Check the cellular connection. Please download Efento mobile application for Android, connect to the sensor -> three dots in the upper right corner -> Cellular status

Supported technologies: [NBIOT]

Current technology: NBIOT

Registration status: REGISTERED

Registration reject cause: 0 0

Signal strength: 2

Communication status: OK

IMEI: 357518080647613

ICCID: 89470800190416017838

Sim card status: OK

Ip address: 10.81.172.63

ECL: LEVEL_1

Cell id: 02120f1c

Tracking area code: 0ce6

Last communication timestamp: 2020-11-23 08:52:13 UTC +01:00

Last status check timestamp: 2020-11-23 08:59:32 UTC +01:00

Seconds since last reset: 86800

If the Registration status is REGISTERED, ECL has any value (LEVEL_0, LEVEL_1, LEVEL_2) and Cell id also has a value, it means that the sensor is registered in the network and the issue is on the integration side.

Please check:

• IP address of the server
• Server port
• APN settings – this has to be checked with your mobile network operator

If all of the points above are correct, the issue is probably in the integration.

Issue: Sensor is registered in the network, my application receives always the same data (retransmissions), “Communication status” shows “MISMATCH”

Your application (the one to which Efento CoAP loader forwards the data) responds with the wrong response status code. The response status code sent by your server must be 2xx.

To make sure that your application responds with the proper status code, send a JSON with measurements using any REST testing application (e.g. POSTMAN) to it. The response status code should be e.g. “201 CREATED”

Issue: Sensor is registered in the network, server does not receive the data, “Communication status” shows “TIMEOUT”

If the IP address, server port, APN are set correctly and APN allows you to access the server, most probably the issue is in the response body sent by your application (the one to which Efento CoAP loader forwards the data) to Efento CoAP loader – the response status code is not 2xx.

Issue: Sensor is registered in the network, but is not able to communicate with the server. My server responds with proper response code and body

Please raise a ticket at help.efento.io. Please attach all the information from the “Cellular status”