Measurements

Endpoint for receiving periodic measurement data from sensors

Receive measurements from sensors

post

Overview

This endpoint is used by the CoAP Loader to forward periodic measurement data from Efento NB-IoT sensors to your platform.

Important: The endpoint paths shown in this documentation (/measurements, /configuration, /device-info) are examples only.

The actual endpoint URLs are fully configurable in the CoAP Loader's application.yml file

When is it called?

• At regular intervals configured on the sensor (e.g., every 15 minutes)

• When a rule/alarm is triggered on the sensor

• When the sensor's buffer is full

What data do you receive?

• Sensor readings: temperature, humidity, pressure, alarms, water/electricity meters, air quality, etc.

• Metadata: battery status, signal strength, measurement timestamps

• Multiple sensors can send data in a single request

Request Structure

Method: POST

Endpoint: Configurable in application.yml under the endpoint key. The path /measurements shown here is just an example.

Headers:

• Content-Type: application/json

• charset: UTF-8

• X-Api-Token: "optional api token" (if configured on sensor via CLOUD_TOKEN parameter)

Body: JSON array containing measurement objects. Each measurement object includes:

• serial - Unique sensor identifier

• battery - Battery status: "ok" or "low"

• signal - Signal quality (0-63, based on RSSI)

• measured_at - UTC timestamp of measurement

• measurement_interval - Interval between measurements in seconds

• next_measurement_at - Scheduled UTC time for next connection

• params - Array of measured parameters (channels 1-6)

Data Filtering - Empty Measurements

The CoAP Loader automatically filters out channels with type "NO_SENSOR" (unconfigured/disabled sensor channels). This may result in:

• Empty measurements array: If all sensor channels are of type NO_SENSOR, the measurements array will be empty and no data will be forwarded to your REST API

• Partial data: Only channels with actual sensors connected will be included in the request

This is normal behavior - sensors can have 1-6 channels, and not all channels need to be physically connected.

Response Options

Your platform must respond with HTTP status code 2xx (e.g., 200, 201, or 204) to confirm receipt.

Option 1: Empty Response

Simply confirms receipt of data:

{}

Option 2: Configuration Update

You can include a JSON object in the response body to remotely change the sensor's settings:

{
  "parameters": [
    {
      "type": "MEASUREMENT_PERIOD",
      "settings": {
        "period": "600"
      }
    }
  ]
}

For a full list of available configuration parameter types and their validation rules, see the ConfigurationParametersReference in the Models section.

Response: Configuration Parameter Validation

When you return configuration parameters in the response:

• Duplicate parameter types: If you send multiple parameters with the same type, the CoAP Loader will keep only the last occurrence and log a warning

• Invalid parameters: Parameters that fail validation (wrong value ranges, missing required fields, etc.) are automatically removed and logged as errors - the remaining valid parameters are still applied to the sensor

• Partial success: Even if some parameters fail validation, the valid ones will be sent to the sensor

Important - Software Version Compatibility

Configuration updates are only supported on sensors with modern firmware. The CoAP Loader determines this by checking the sensor's hash value:

• hash = "0": Deprecated software version - configuration changes are NOT sent to the sensor (the CoAP Loader will log a warning and skip configuration)

• hash > "0": Modern software version - configuration changes can be applied normally

If you send configuration parameters in the response for a sensor with hash="0", they will be ignored by the CoAP Loader.

Header parameters

X-Api-TokenstringOptional

Optional API token for authentication (if configured)

Example: your_api_token

Content-TypestringRequiredDefault: application/json

charsetstringRequiredDefault: UTF-8

Body

application/json

Responses

401

Unauthorized.

HTTP to CoAP mapping: HTTP 401 or 403 will be converted to CoAP 4.01 UNAUTHORIZED.

Sensor behavior: The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.

No content

403

Forbidden.

HTTP to CoAP mapping: HTTP 401 or 403 will be converted to CoAP 4.01 UNAUTHORIZED.

Sensor behavior: The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.

2XX

Success - Data received successfully.

You can return an empty response or include configuration parameters to update the sensor. See endpoint description above for details on parameter validation and error handling.

HTTP to CoAP mapping: Any 2xx HTTP status code (200, 201, 204, etc.) will be converted to CoAP 2.01 CREATED.

Sensor behavior: The sensor receives the response and applies any configuration parameters included in the response body.

application/json

3XX

Redirection.

HTTP to CoAP mapping: Any 3xx HTTP status code (301, 302, 304, etc.) will be converted to CoAP 5.00 INTERNAL SERVER ERROR.

Sensor behavior: The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.

4XX

Client Error.

HTTP to CoAP mapping: Any 4xx HTTP status code (except 401/403) will be converted to CoAP 4.00 BAD REQUEST.

Sensor behavior: The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.

5XX

Server Error.

HTTP to CoAP mapping: Any 5xx HTTP status code (500, 502, 503, etc.) will be converted to CoAP 5.00 INTERNAL SERVER ERROR.

Sensor behavior: The sensor does NOT receive any configuration updates. The sensor will retry according to its retry policy.

post

/measurements

HTTPcURLJavaScriptPython

POST /measurements HTTP/1.1
charset: UTF-8
Content-Type: application/json
Accept: */*
Content-Length: 540

{
  "measurements": [
    {
      "serial": "282C024FFFB1",
      "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,
          "status": "ok"
        }
      ]
    },
    {
      "serial": "282C024FFFB2",
      "battery": "ok",
      "signal": 21,
      "measured_at": "2026-02-09 15:28:21",
      "measurement_interval": 180,
      "next_measurement_at": "2026-02-09 18:58:21",
      "params": [
        {
          "channel": 1,
          "type": "temperature",
          "value": "12",
          "status": "ok"
        },
        {
          "channel": 2,
          "type": "humidity",
          "value": "51",
          "status": "ok"
        }
      ]
    }
  ]
}

No content