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
    4. endpointConfiguration – address of the REST endpoint where you want to receive sensors configuration
    5. endpointDeviceInfo – address of the REST endpoint where you want to receive technical information about the devices (signal parameters, etc.)
  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

EFENTO Gateway API specification v.3.0
ENDPOINT /api/v3/measurements
METHOD POST
HEADERS Content-Type: application/json

charset=UTF-8

X-Api-Token:”optional api token

BODY
{

  "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" : [

      {
        "status" : [string] // ok / error (if the device was not able to take measurement)
        "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" : [

      { "status" : ok, "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" : [

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

      { "status" : ok, "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" : [

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

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

      { "status" : ok, "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" : [
 
      { "status" : ok, "channel" : 1, "type" : "open-close", "value" : 0},

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

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

    ]

  }

 ]

}
CORRECT RESPONSE Response with response status code 2xx (e.g. 201, 204, 205).

Response body can be empty or can be used to send the new configuration to the sensor. Details of the new configuration settings are described in the next chapter.

INCORRECT RESPONSE All the other response status codes.

Signal quality indicator returns values based on the RSSI

Value RSSI [dBm] Interpretation
[0; 15] [-110; -95] Marginal
[16; 25] [-94; -85] OK
[26; 35] [-84; -75] Good
[36; 63] [-74; -48] Excellent

Parameter type in params can have the following values:

  • temperature
  • humidity
  • pressure
  • pressure_diff
  • open-close
  • iaq
  • flooding
  • pulse_counter
  • electricity_usage
  • water_usage
  • soil_moisture
  • co_gas
  • no2_gas
  • h2s_gas
  • ambient_light
  • pm_1_0
  • pm_2_5
  • pm_10_0
  • noise_level
  • nh3_gas
  • ch4_gas
  • high_pressure
  • distance_mm
  • water_meter_acc
  • co2_gas
  • humidity_accurate
  • static_iaq
  • co2_equivalent
  • breath_voc
  • percentage
  • voltage
  • current
  • elec_meter_acc
  • output_control

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

CORRECT RESPONSE Response with response status code 2xx (e.g. 201, 204, 205).

Response body can be empty or can be used to send the new configuration to the sensor. Details of the new configuration settings are described in the next chapter.

RESPONSE BODY
{

  "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":180,

  "supervisionPeriodMode":"VALUE",

  "requestMemoryReset":false,

  "bands":[

    1

  ],

  "alarmRules":[

    {

      "slotNumbers":[

        0

      ],

    "condition":"HIGH_THRESHOLD",

    "action”: “TRIGGER_TRANSMISSION",

    "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

dataEndpoint // string, length: 1 – 16

configurationEndpoint // string, length: 1 – 16

deviceInfoEndpoint // string, length: 1 – 16

timeEndpoint // string, length: 1 – 16

cloudTokenCoapOption // number, 1 – 64999

cloudTokenCoapOptionMode // enum (string): “NOT_SEND”, “VALUE”, “SEND_IN_PAYLOAD”

payloadSignatureCoapOption // number, 1 – 64999

payloadSingatureCoapOptionMode // enum (string): “NOT_SEND”, “VALUE”, “NO_PAYLOAD”

dnsServerIp // array of 4 integers, possible values: 0 – 255

dnsTtlConfig // number, 1 – 864000

dnsTtlConfigMode // enum (string): “NOT_SEND”, “VALUE”, “ACCEPT”, “FAILED”

modemUpdateRequest // string, length: 1- 48

networkTroubleshooting // number, 1 – 2

encryptionKey // string, length: 1 – 16

encryptionKeyMode // enum (string): “NOT_SEND”, “VALUE”, “HEX_VALUE”, “DISABLED”

apnUserName // string, length: 1 – 31

apnUserNameMode // enum (string): “NOT_SEND”, “VALUE”, “AUTO”

apnPassword // string, length 1 – 31

apnPasswordMode // enum (string): “NOT_SEND”, “VALUE”, “AUTO”

ledConfig // array of integers, param of single 

     ledConfig[0] – green LED // Period of LEDs flashing (5-600 seconds in 5 seconds resolution):

     ledConfig[1] – red LED // Period of LEDs flashing (5-600 seconds in 5 seconds resolution):

// ledConfig[2] – ledConfig[7] Time from entering the normal state, after which the LED indicates is turned off (0-240 minutes in 1 minute resolution, or 255 for always turned on):

     ledConfig[2] – flashing red led on communication problem

     ledConfig[3] – flashing red led on a sensor problem

     ledConfig[4] – flashing red led on a low power

     ledConfig[5] – flashing green led on measurement

     ledConfig[6] – flashing green led on transmission 

     ledConfig[7] – flashing green led to indicate sensor’s proper operation

     ledConfig[8] – Blink duration ( 20 – 1000 ms in 5 ms resolution)

calibrationParametersRequest // object (calibrationParametersRequest), param of objects, described below

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

calendars // array of object (calendar), param of single calendar object, described below

outputControls // array of object (output control), param of single object, described below

 

CALIBRATION PARAMETERS REQUEST PARAMETERS

calibrationRequest // number, 1 – 6

channelAssignment // number, possible hex values: 0x0, 0x1, 0x4, 0x6, 0x8, 0x9,

0xA, 0xB, 0xC, 0xD, 0xE, 0x10,

0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19,

0x1A, 0x1B, 0x1C, 0x1E, 0x1F, 0x20,

0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 

0x29, 0x2A, 0x2B, 0x2C, 0x30,

0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38,

0x39, 0x3A, 0x3B, 0x3C, 0x3D, 0x3E, 0x3F, 0x40,

0x41

parameters // array of integers, max size = 8

 

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”

action //enum (string)

“TRIGGER_TRANSMISSION”

“NO_ACTION”

“TRIGGER_TRANSMISSION_WITH_ACK”

alarmRuleType // enum (string):

“TEMPERATURE”

“HUMIDITY”

“ATMOSPHERIC_PRESSURE”,

“DIFFERENTIAL_PRESSURE”,

“PULSE_CNT”,

“ELECTRICITY_METER”,

“WATER_METER”,

SOIL_MOISTURE”,

“CO_GAS”,

“NO2_GAS”,

“H2S_GAS”,

“AMBIENT_LIGHT”,

“PM_1_0”,

“PM_2_5”,

“PM_10_0”,

“NOISE_LEVEL”,

“NH3_GAS”,

“CH4_GAS”,

“HIGH_PRESSURE”,

“DISTANCE_MM”,

“WATER_METER_ACC_MINOR”,

“WATER_METER_ACC_MAJOR”,

“HUMIDITY_ACCURATE”,

“STATIC_IAQ”,

“C02_EQUIVALENT”,

“BREATH_VOC”,

PERCENTAGE”,

“VOLTAGE”,

“CURRENT”,

“PULSE_CNT_ACC_MINOR”,

“PULSE_CNT_ACC_MAJOR”,

“ELEC_METER_ACC_MINOR”,

“ELEC_METER_ACC_MAJOR”,

“PULSE_CNT_ACC_WIDE_MINOR “,

“PULSE_CNT_ACC_WIDE_MAJOR”,

“CURRENT_PRECISE”

threshold // number

hysteresis // number

averageMode // enum (string): “MOVING_AVERAGE”, “WINDOW_MODE”, “CONSECUTIVE_SAMPLES”

averageNumberOfSamples // number, 1 – 10

logicOperator // enum (string): “AND”, “OR”

selectedRules // array of integers, possible values: 1 – 12

negatedRules // array of integers, possible values: values included in selectedRules

actionDelay // number, 0 – 8640010

returnDelay // number, 0 – 8640001, max parameter value disables action triggering on rule deactivation

numberOfMeasurementsToEverySend // number, 1 – 500

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 action
    • set alarmRuleType
    • set threshold
    • set hysteresis
    • set averageMode
    • set averageNumberOfSamples

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

  • BINARY_CHANGE_STATE
    • set slotNumbers
    • set action
    • other fields set null (alarmRuleType, threshold, hysteresis, averageMode, averageNumberOfSamples)
  • LOGIC_OPERATOR
      • set logicOperator
      • set action
      • set selectedRules
      • set negatedRules
      • set actionDelay
      • set returnDelay
      • other fields set null 
  • ON_MEASUREMENT
    • set numberOfMeasurementsToEverySend
    • set action
    • set selectedRules (optional, choose only one number)
    • set negatedRules (optional)
    • other fields set null

 

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

  • TEMPERATURE
    • range: -273.2 – 4000.0
      • resolution: 0.1
  • HUMIDITY
    • range: 0 – 100
    • resolution: 1
  • IAQ
    • range: 0 – 500
    • 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
  • SOIL_MOISTURE
    • range: -1000 – 0
    • resolution: 1
  • CO_GAS
    • range:0 – 1000000
    • resolution: 1
  • NO2_GAS
    • range:0 – 1000000
    • resolution: 1
  • H2S_GAS
    • range:0 – 80000.00
    • resolution: 0.01
  • AMBIENT_LIGHT
    • range:-0 – 100000.0
    • resolution: 0.1
  • PM_1_0
    • range:0 – 1000
    • resolution: 1
  • PM_2_5
    • range:0 – 1000
    • resolution: 1
  • PM_10_0
    • range:0 – 200
    • resolution: 1
  • NOISE_LEVEL
    • range:0 – 8000000.0
    • resolution: 0.1
  • NH3_GAS
    • range:0 – 1000000
    • resolution: 1
  • CH4_GAS
    • range:0 – 1000000
    • resolution: 1
  • HIGH_PRESSURE
    • range: 1 – 200000
    • resolution: 1
  • DISTANCE_MM
    • range: 1 – 100000
    • resolution: 1
  • WATER_METER_ACC_MINOR
    • range: 1 – 1000000
    • resolution: 1
  • WATER_METER_ACC_MAJOR
    • range: 1 – 1000000
    • resolution: 1
  • CO2_GAS
    • range: 1 – 1000000
    • resolution: 1
  • HUMIDITY_ACCURATE
    • range: 0.1 – 100.0
    • resolution: 0.1
  • STATIC_IAQ
    • range :1 – 10000
    • resolution: 1
  • C02_EQUIVALENT
    • range: 1 – 1000000
    • resolution: 1
  • BREATH_VOC
      • range: 0 – 100 000
      • resolution: 1
  • PERCENTAGE
      • range: 0 – 100.00
      • resolution: 0.01
  • VOLTAGE
      • range: 0 – 100 000
      • resolution: 0.1
  • CURRENT
      • range: 0 – 10 000
      • resolution: 0.01
  • PULSE_CNT_ACC_MINOR
      • range: 0 – 1 000 000
      • resolution: 1
  • PULSE_CNT_ACC_MAJOR
      • range: 0 – 1 000 000 000
      • resolution: 1
  • ELEC_METER_ACC_MINOR
      • range: 0 – 1 000 000 
      • resolution: 1
  • ELEC_METER_ACC_MAJOR
      • range: 0 – 1 000 000 000
      • resolution: 1
  • PULSE_CNT_ACC_WIDE_MINOR
      • range: 0 – 999 999
      • resolution: 1
  • PULSE_CNT_ACC_WIDE_MAJOR
      • range: 0 – 999 999 000 000
      • resolution: 1
  • CURRENT_PRECISE
    • range: 0 – 8 000
    • resolution: 0.001

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

  • TEMPERATURE
    • range: 0.1 – 4273.2
      • resolution: 0.1
  • HUMIDITY
    • range: 1 – 100
    • resolution: 1
  • IAQ
    • range: 1 – 500
    • resolution: 1
  • ATMOSPHERIC_PRESSURE
    • range: 0.1 – 1999.0
      • resolution: 0.1
  • DIFFERENTIAL_PRESSURE
    • range: 1 – 20000.0
      • resolution: 1
  • PULSE_CNT
    • range: 1 – 8000000
    • resolution: 1
  • ELECTRICITY_METER
    • range: 1 – 8000000
      • resolution:  1
  • WATER_METER
    • range:1 – 8000000
    • resolution: 1
  • SOIL_MOISTURE
    • range:1 – 1000
    • resolution: 1
  • CO_GAS
    • range:1 – 1000000
    • resolution: 1
  • NO2_GAS
    • range:1 – 1000000
    • resolution: 1
  • H2S_GAS
    • range:0.01 – 80000.00
    • resolution: 0.01
  • AMBIENT_LIGHT
    • range:-0.1 – 100000.0
    • resolution: 0.1
  • PM_1_0
    • range:1 – 1000
    • resolution: 1
  • PM_2_5
    • range:1 – 1000
    • resolution: 1
  • PM_10_0
    • range:1 – 200
    • resolution: 1
  • NOISE_LEVEL
    • range:0.1 – 8000000.0
    • resolution: 0.1
  • NH3_GAS
    • range:1 – 1000000
    • resolution: 1
  • CH4_GAS
    • range:1 – 1000000
    • resolution: 1
  • HIGH_PRESSURE
    • range: 1 – 200000
    • resolution: 1
  • DISTANCE_MM
    • range: 1 – 100000
    • resolution: 1
  • WATER_METER_ACC_MINOR
    • range: 1 – 1000000
    • resolution: 1
  • WATER_METER_ACC_MAJOR
    • range: 1 – 1000000
    • resolution: 1
  • CO2_GAS
    • range: 1 – 1000000
    • resolution: 1
  • HUMIDITY_ACCURATE
    • range: 0.1 – 100.0
    • resolution: 0.1
  • STATIC_IAQ
    • range :1 – 10000
    • resolution: 1
  • C02_EQUIVALENT
    • range: 1 – 1000000
    • resolution: 1
  • VOLTAGE
      • range: 0.1 – 100 000
      • resolution: 0.1
  • CURRENT
    • range: 0.01 – 10 000
    • resolution: 0.01
  • PULSE_CNT_ACC_MINOR
      • range: 1 – 1 000 000
      • resolution: 1
  • PULSE_CNT_ACC_MAJOR
      • range: 1 – 1 000 000 000
      • resolution: 1
  • ELEC_METER_ACC_MINOR
      • range: 1 – 1 000 000 
      • resolution: 1
  • ELEC_METER_ACC_MAJOR
      • range: 1 – 1 000 000 000
      • resolution: 1
  • PULSE_CNT_ACC_WIDE_MINOR
      • range: 1 – 999 999
      • resolution: 1|
  • PULSE_CNT_ACC_WIDE_MAJOR
      • range: 1 – 999 999 000 000
      • resolution: 1
  • CURRENT_PRECISE
      • range: 0.001 – 8 000
      • resolution: 0.001

CALENDAR PARAMETERS

enableRules // array of integers, possible values 1 – 12, max length = 12

type // enum (string): “DISABLED”, “WEEK”

days // array of integers, max length = 7 possible values: 0 – 6  ( 0 – Sunday … 6 – Saturday)  

fromTime // number, 0 – 1439 (minutes from midnight)

toTime // number, 0 – 1439 (minutes from midnight)

timezone // number, -48 – 56 (encoded as number of 15 minutes octets, example: UTC+1 -> timezone = 4)

 

OUTPUT CONTROL

channelNumber // integer, possible values 1 – 6

state // integer, possible values 0 – 1, (0 – OFF 1 – ON)

Examples

New settings Response body (JSON)
Set:

  • measurement period to 5 minutes (300s)
  • transmission interval to 1 hour (3600s)
{

  "measurementPeriodBase":300,

  "measurementPeriodFactor":1,

  "transmissionInterval":3600

}
Set:

  • APN to value “nbiot.com”
{

  "apn":"nbiot.com",

  "apnMode":"VALUE"

}

Set:

  • Server address to “45.45.45.45”
  • Server port to “1212”
  • Cloud token to “IMEI”
{

  "serverDataIp":"45.45.45.45",

  "serverDataPort":1212,

    "cloudTokenConfig":"CLOUD_TOKEN_IMEI"

}
Set:

  • Alarm rule “if the temperature on slot 0 is over 5 C, trigger the transmission”
  • Alarm rule “if the humidity on slot 1 is below 50%, trigger the transmission”
  • Alarm rule “if the change of the temperature on slot 0 is over 0.5C, trigger the transmission”
{

  "alarmRules":[

  {

    "slotNumbers":[

      0

    ],

    "condition":"HIGH_THRESHOLD",
    
    "action": "TRIGGER_TRANSMISSION"

    "alarmRuleType":"TEMPERATURE",

    "threshold":5,

    "hysteresis":0,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 1

  },

  {

    "slotNumbers":[

      1

    ],

    "condition":"LOW_THRESHOLD",

    "action": "TRIGGER_TRANSMISSION"

    "alarmRuleType":"HUMIDITY",

    "threshold":50,

    "hysteresis":0,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 1

  },

  {

    "slotNumbers":[

      0

    ],

    "condition":"DIFF_THRESHOLD",

    "action": "TRIGGER_TRANSMISSION"

    "alarmRuleType":"TEMPERATURE",

    "threshold":0.5,

    "hysteresis":0,

    "averageMode":"MOVING_AVERAGE",

    "averageNumberOfSamples": 1

    }

 ]

}
  • Remove alarm rules 0,1,2,4,5,6,7,8,9,10,11 from the sensor
  • Set rule 3 to “if the temperature on slot 0 is below 15 C, trigger the transmission”
  • Set rule 4 to “if the temperature on slot 0 is over 25 C, trigger the transmission”
  • Set rule 6 to “trigger transmission every 10 measurement if rule 4 is not activated”
  • Set rule 7 to “if rule 4 or 6 is active, trigger transmission after 1s, triggering after deactivation disabled”
  • Set calendar 2 to “enable rule 1, 8 and 12 every Sunday, Thursday and Saturday between 1:00 and 3:00 in UTC-2”
  • Remove calendar 1,3,4,5,6 from the sensor

Sensors can store up to 12 rules, with ids 0-11. Settings of each rule are sent in an array in JSON. All rules are equally important – there is no difference on which slot the rule is kept.

Sensors can store up to 6 calendars. Settings of each calendar are sent in an array in JSON. All calendars are equally important – there is no difference on which slot the calendar is kept.

{
        "alarmRules":[
                 {
                     "condition":"DISABLED"
                 },
                  {
                     "condition":"DISABLED"
                 },
                 {
                    "slotNumbers":[
                       0
                    ],
                    "condition":"LOW_THRESHOLD",
                    "action": "TRIGGER_TRANSMISSION",
                    "alarmRuleType":"TEMPERATURE",
                    "threshold":15,
                    "hysteresis":0,
                    "averageMode":"MOVING_AVERAGE",
                    "averageNumberOfSamples": 1
                },
                 {
                     "slotNumbers":[
                        0
                     ],
                     "condition":"HIGH_THRESHOLD",
                     "action": "TRIGGER_TRANSMISSION",
                     "alarmRuleType":"TEMPERATURE",
                     "threshold":25,
                     "hysteresis":0,
                     "averageMode":"MOVING_AVERAGE",
                     "averageNumberOfSamples": 1
                 },
                {
                     "condition":"DISABLED"
                 },
                 {
                    "condition":"ON_MEASUREMENT",
                    "action": "TRIGGER_TRANSMISSION",
                    "selectedRules": [4],
                    "negatedRules": [4],
                    "numberOfMeasurementsToEverySend": 10
                },
                  {
                     "condition":"LOGIC_OPERATOR",
                     "action":"TRIGGER_TRANSMISSION",
                     "logicOperator": "OR",
                     "selectedRules":[4,6],
                     "negatedRules":[],
                     "actionDelay": 1,
                     "returnDelay": 864001,
                 },
                  {
                     "condition":"DISABLED"
                 },
                 {
                     "condition":"DISABLED"
                 },
                  {
                     "condition":"DISABLED"
                 },
                  {
                     "condition":"DISABLED"
                 },
                  {
                     "condition":"DISABLED"
                 }
        ],
        "calendars":[
                 
                {
                     "type":"DISABLED",
                 },
                {
                     "enableRules": [1 ,8, 12],
                     "type":"WEEK",
                     "days": [0,4,6],
                     "fromTime": 60,
                     "toTime": 180,
                     "timezone": -8,
                 },
                {
                     "type":"DISABLED",
                 },
                {
                     "type":"DISABLED",
                 },
                {
                     "type":"DISABLED",
                 },
                {
                     "type":"DISABLED",
                 }
      
        ]
      } 

 

Forwarding sensor configuration

On the first communication with the server or on configuration change, each sensor will send its current configuration to the server. The configuration will be forwarded by the CoAP loader to the user’s application, to endpoint  endpointConfiguraiton defined in the ‘application.yml’. The correct response to the payload send to this endpoint is 2XX (e.g. ‘201’)

ENDPOINT To be set in application.yml file (endpointConfiguration)
METHOD POST
HEADERS Content-Type: application/json

charset=UTF-8

X-Api-Token:”optional api token

BODY
{

 

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

"timestamp":[string], // 

"partsCount" : [number], // number of configuration parts

"partIndex" : [number], // index of current configuration part

"hash" : [number], // Configuration hash (changes with each change of configuration)

"parameters" : [

  {

               "type" : [String], // Values described below

               “settings”:

  {

               "settingName” : “settingValue” [string], // setting name to value

              }

           ]

}





Example:

{

"serialNumber" : "282C024FFFB1",

"timestamp": 1,

"partsCount" : 1,

"partsIndex" : 1,

"hash" : "1",

"parameters" : [

{ 

                             “type”: “ACK_INTERVAL”,

                             “settings”: {

                              “mode” : “CUSTOM”,

                              “interval”: “3600”

                              }

                          }

                                 ]

},

Parameters

Type Settings

Values

ACCEPT_WITHOUT_TESTING                     flag* Boolean  [true / false]
ACK_INTERVAL                               mode*   

interval      with mode CUSTOM only   

ALWAYS / CUSTOM

Integer  [180 – 2592000 sec]

APN                                        interval      with mode CUSTOM only  

apn           with mode CUSTOM only   

apnUsername    

apnPassword    

Integer  [180 – 2592000 sec]

AUTO / CUSTOM

String [max 49 characters] 

String [max 31 characters]

BANDS                                      bands*  String (integers separated by comma) example: ‘1,2,3’

                                                                                           [1, 2, 3, 4, 5, 6, 8, 12, 13, 17, 18, 19, 20, 25, 26, 28, 66, 71, 85]

BLE_TURNOFF_TIME                           mode*                                   

time          with mode CUSTOM only         

ALWAYS_ON / CUSTOM

Integer  [60 – 604800 sec]

BLE_TX_POWER_LEVEL                         level* Integer  [1 – 4]
CELLULAR_CONFIG                            parameters*                                       String (integers seperated by comma, without size – index 0)

                                                                                           max number of integers: 11, example: ‘1,2,3’

CLOUD_TOKEN                                mode*                          

token        with mode CUSTOM only                   

DISABLED / CUSTOM / IMEI

String

CLOUD_TOKEN_COAP_OPTION                    mode*

optionId       with mode CUSTOM only  

AUTO / CUSTOM

Integer  [1 – 65000]

CONFIGURATION_ENDPOINT                     endpoint*                                         String [max 16 characters]
DATA_ENDPOINT                              endpoint*  String [max 16 characters]
DEVICE_INFO_ENDPOINT                       endpoint*  String [max 16 characters]
DNS_SERVER                                 ip*  String [max 16 characters]
DNS_TTL_CONFIG                             mode*   

ttl          with mode CUSTOM only

CCEPT_TTL_FROM_DNS / AFTER_COMMUNICATION_FAILED / CUSTOM

Integer  [1 – 864000 sec]

ENCRYPTION_KEY                             key*                                              String [max 16 characters]
LED_CONFIG                                 parameters*   String (integers seperated by comma) example: ‘1,2,3’
MEASUREMENT_PERIOD                         period*   Integer  [1 – 65535 sec]
MEASUREMENT_PERIOD_FACTOR                  factor*     Integer  [1 – 65535]
NETWORK_TROUBLESHOOTING                    mode*    ENABLED / DISABLED
PAYLOAD_SIGNATURE_COAP_OPTION              mode*  

optionId       with mode CUSTOM only    

AUTO / CUSTOM

Integer  [1 – 65000]

PLMN                                       mode* 

time          with mode CUSTOM only   

AUTO / CUSTOM

Integer  [100 – 999999]

REQUEST_DISABLE_MODEM                      time*                                             Integer  [180 – 604800 sec]
REQUEST_MEMORY_RESET                       flag* Boolean  [true / false]
REQUEST_DEVICE_INFO                        mode*  

period        with mode PERIODICALLY only

NEVER / ALWAYS / PERIODICALLY

Integer  [1 – 240 h]

REQUEST_FIRMWARE_UPDATE                    flag*       Boolean  [true / false]
REQUEST_RUNTIME_ERRORS_CLEAR               flag*    Boolean  [true / false]
REQUEST_MODEM_UPDATE                       string*    

mode*     

period      with mode PERIODICALLY only    

String [max 48 characters]

ONCE / PERIODICALLY

Integer  [1 – 240 h]

SERVER_DATA                                ip*   

port*    

String [valid ip address]

Integer  [1 – 65535]

SERVER_UPDATE                              ip*                                            

portCoap*                                          

String  [valid ip address]

Integer  [1 – 65535]

SUPERVISION_PERIOD                         portUdp*                         

mode*                                                            

Integer  [1 – 65535]

DISABLED / CUSTOM

TIME_ENDPOINT                              endpoint* String [max 16 characters]
TRANSMISSION_INTERVAL                      interval*  Integer  [60 – 604800 sec]
TRANSFER_LIMIT                             mode*     

time          with mode CUSTOM only   

DISABLED / CUSTOM

Integer  [180 – 65534 sec]

TRANSFER_LIMIT_TIMER                       mode*

time          with mode CUSTOM only  

DISABLED / CUSTOM

Integer  [180 – 65534 sec]

CALIBRATION                                channelNumbers*       

channelAssignment*             

parameters*                                                                                   

String (integers separated by comma, no duplicates) example: ‘1,2,3’                                                                         [1 – 6]

Integer

String (integers separated by comma, max number of integers: 8) example: ‘1,2,3’

CHANNEL_CONTROL_1  … CHANNEL_CONTROL_6                         controlParameters*                                String (integers separated by comma) example: ‘1,2,3’

Rule parameters:

Type : RULE_1 … RULE_12

Setting Values
channelNumbers                                    String (integers separated by comma, no duplicates) example: ‘1,2,3’

                                                                                           [1 – 6]

type                                              TEMPERATURE [°C] / HUMIDITY [%] / ATMOSPHERIC_PRESSURE [hPa] 

                                                                                           DIFFERENTIAL_PRESSURE [Pa] / IAQ [-] / PULSE_CNT [-] 

                                                                                           ELECTRICITY_METER [Wh] / WATER_METER [l/min] 

                                                                                           SOIL_MOISTURE [kPa] / CO_GAS [ppm] / NO2_GAS [ppm] 

                                                                                           H2S_GAS [ppm] / AMBIENT_LIGHT [lx] / PM_1_0 [µg/m^3] 

                                                                                           PM_2_5 [µg/m^3] / PM_10_0 [µg/m^3] / NOISE_LEVEL [dB] 

                                                                                           NH3_GAS [ppm] / CH4_GAS [ppm] / HIGH_PRESSURE [kPa] 

                                                                                           DISTANCE_MM [mm] / WATER_METER_ACCUMULATIVE [m3] 

                                                                                           CO2_GAS [ppm] / CO2_EQUIVALENT [ppm] / BREATH_VOC [ppm] 

                                                                                           PERCENTAGE [%] / VOLTAGE [mV] / CURRENT [mA] 

                                                                                           PULSE_COUNTER_ACCUMULATIVE [-] / ELECTRICITY_METER_ACCUMULATIVE [kWh] 

action                                            ACTION_TRIGGER_TRANSMISSION / ACTION_NO_ACTION / ACTION_TRIGGER_TRANSMISSION_WITH_ACK
threshold                                         Number
hysteresis                                        Number
averageMode                                       MOVING_AVERAGE / WINDOW_MODE / CONSECUTIVE_SAMPLES
averageNumberOfSamples                            Integer [1 – 10]
logicOperator                                     AND / OR
selectedRules                                     String (integers seperated by comma, no duplicates) example: ‘1,2,3’

                                                                                           [1 – 12]

negatedRules                                      String (integers seperated by comma, no duplicates) example: ‘1,2,3’

                                                                                           [1 – 12]

actionDelay                                       Integer [0 – 864000]
returnDelay                                       Integer [0 – 864001]
measurementTransmission                           Integer [1 – 500]

Rule calendars:
Type: RULE_CALENDAR_1 … RULE_CALENDAR_6

Setting Value
selectedRules*                                                                      String (integers separated by comma, no duplicates) example: ‘1,2,3’

RULE_CALENDAR_2                                                                            [1 – 12]

type*                                             DISABLED / WEEK
days                                                                                        String (enums separated by comma) example: ‘MONDAY,SATURDAY’

                                                                                           MONDAY / TUESDAY / WEDNESDAY / THURSDAY / FRIDAY / SATURDAY / SUNDAY

from                                                                                     Integer (minutes from midnight) [0 – 1439]
to                                       Integer (minutes from midnight) [0 – 1439]
timezone                                                                                                                             Integer (number of 15 minute offsets) [-48 – 56]

Forwarding device information

On the server’s request (requestDeviceInfo flag send in the response body) the device sends detailed information about its status and network related parameters. This information will be forwarded by the CoAP loader to the user’s application, to endpoint  endpointDeviceInfo defined in the ‘application.yml’. The correct response to the payload send to this endpoint is 2XX (e.g. ‘201’)

ENDPOINT To be set in ‘application.yml’ file (endpointDeviceInfo)
METHOD POST
HEADERS Content-Type: application/json

charset=UTF-8

X-Api-Token:”optional api token

BODY
{

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

"softwareVersion":[string], // software version

"runtimeInfo" : {

                     “uptime”: [number],

                     “confirmableMessagesAttemps”: [number], // counter of confirmable message attempts

                     “nonConfirmableMessagesAttempts”: [number], // counter of non-confirmable message attempts

                     “succeededMessages”: [number], // counter of succeeded messages

                     “mcuTemperature”: [number], // mcu temperature in Celsius

                     “minBatteryVoltage”: [number], // min battery voltage in mV

                     “minBatteryMcuTemperature”: [number], // mcu temperature in celsius while the minimum battery voltage was reached

                     “batteryResetTimestamp”: [number], // battery reset timestamp (unix timestamp)

                     “maxMcuTemperature”: [number], // max mcu temperature in celsius

                     “minMcuTemperature”: [number], // min mcu tempreature in celsius

                     “runtimeErrors”: [number list] // table of runtime errors, max length: 20

             }

             “modemInfo”: {

                     “modemType”: [string] // MODEM_TYPE_UNSPECIFIED,             MODEM_TYPE_BC66, MODEM_TYPE_BC66NA 

                     “parameters”: [] // parameters list, described below

              }

"commitId":[string], // commit Id

"cloudToken":[string], // cloud token

"memoryStatistics":[number list], // memory statistics

"updateTimestamp":[number], // update timestamp

"updateStatus":[number], // update status






}





Example:

{

"serialNumber" : 282C024FFFB1

"softwareVersion": 1546,

"runtimeInfo" : {

                     “uptime”: 1,

                     “confirmableMessagesAttemps”: 1,

                     “nonConfirmableMessagesAttempts”: 1,

                     “succeededMessages”: 1,

                     “mcuTemperature”: 21,

                     “minBatteryVoltage”: 5,

                     “minBatteryMcuTemperature”: 20,

                     “batteryResetTimestamp”: 1,

                     “maxMcuTemperature”: 1

                     “minMcuTemperature”: 1,

                     “runtimeErrors”: [15,2,3]

             }

             “modemInfo”: {

                     “modemType”: MODEM_TYPE_BC66,

                     “parameters”: [5,12,3]

              }

"commitId": e0e8556,

"cloudToken":”AAABABRFFE”, 

"memoryStatistics": [12,3,4],

"updateTimestamp": 1,

"updateStatus": 1




}
CORRECT RESPONSE Response with response status code 2xx (e.g. 201, 204, 205).

Response body can be empty or can be used to send the new configuration to the sensor. Details of the new configuration settings are described in the next chapter.

INCORRECT RESPONSE All the other response status codes.

‘Modem info’ parameters

parameters[0] – sc_EARFCN – Range: [0:262143]. Unknown value: -1                                                          

parameters[1] – sc_EARNFCN_offset – Range: [0:4] mapped to [-2, -1, -0.5, 0, 1]. Unknown value: -1                        

parameters[2] – sc_PCI – Range: [0:502]. Unknown value: -1                                                                

parameters[3] – sc_Cell id – Range: [1:268435456]. Unknown value: 0                                                       

parameters[4] – sc_RSRP – [dBm] – Range: [-140:-44]. Unknown value: 0                                                     

parameters[5] – sc_RSRQ – [dB] – Range: [-20:-3]. Unknown value: 0                                                        

parameters[6] – sc_RSSI – [dBm] – Range: [-110:-3] Unknown value: 0                                                       

parameters[7] – sc_SINR – [dB] – Range: [-10:30]. Unknown value: 31                                                       

parameters[8] – sc_Band – Range: [see module supported bands]. The current serving cell band. Unknown value: -1           

parameters[9] – sc_TAC – Range: [0:65536]. Unknown value: -1                                                              

parameters[10] – sc_ECL – Range: [0:2]. Unknown value: -1                                                                 

parameters[11] – sc_TX_PWR – [0.1cBm] – Range [-440:230]. Unknown value: -1000                                            

parameters[12] – OP_MODE – Range: [0:3]. Unknown value: -1                                                                

parameters[13] – nc_EARFCN – Range: [0:262143]. Unknown value: -1                                                         

parameters[14] – nc_EARNFCN_offset – Range: [0:4] mapped to [-2, -1, -0.5, 0, 1]. Unknown value: -1                       

parameters[15] – nc_PCI – Range: [0:502]. Unknown value: -1                                                               

parameters[16] – nc_RSRP – [dBm] – Range: [-140:-44]. Unknown value: 0                                                    

parameters[17] – RLC_UL_BLER – Range: [0:100]. Unknown value: -1                                                          

parameters[18] – RLC_DL_BLER – Range: [0:100]. Unknown value: -1                                                          

parameters[19] – MAC_UL_BLER – Range: [0:100]. Unknown value: -1                                                          

parameters[20] – MAC_DL_BLER – Range: [0:100]. Unknown value: -1                                                          

parameters[21] – MAC_UL_TOTAL_BYTES – Range: [0:2147483647]. Unknown value: -1                                            

parameters[22] – MAC_DL_TOTAL_BYTES – Range: [0:2147483647]. Unknown value: -1                                            

parameters[23] – MAC_UL_total_HARQ_Tx – Range: [0:2147483647]. Unknown value: -1                                          

parameters[24] – MAC_DL_total_HARQ_Tx – Range: [0:2147483647]. Unknown value: -1                                          

parameters[25] – MAC_UL_HARQ_re_Tx – Range: [0:2147483647]. Unknown value: -1                                             

parameters[26] – MAC_DL_HARQ_re_Tx – Range: [0:2147483647]. Unknown value: -1                                             

parameters[27] – RLC_UL_tput – Range: [0:2147483647]. Unknown value: -1                                                   

parameters[28] – RLC_DL_tput – Range: [0:2147483647]. Unknown value: -1                                                   

parameters[29] – MAC_UL_tput – Range: [0:2147483647]. Unknown value: -1                                                   

parameters[30] – MAC_DL_tput – Range: [0:2147483647]. Unknown value: -1                                                   

parameters[31] – sleep_duration – [0.1s] – Range: [0:2147483647]. Unknown value: -1                                       

parameters[32] – Rx_time – [0.1s] – Range: [0:2147483647]. Unknown value: -1                                              

parameters[33] – Tx_time – [0.1s] – Range: [0:2147483647]. Unknown value: -1

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”