Duck Integration Document

Sensemore Duck is a compact IoT data acquisition hardware to collect process data not only vibration, temperature, and pressure but also whole analog data such as; mass flow rate, speed, current, etc.

Chekout Duck data sheet http://sensemore.io/
Chekout Duck installation guide http://sensemore.io/

Before starting to speak about Duck system integration, configure your Duck's MQTT, NTP and HTTP settings.

Accessing Configuration Page

Shortly after the Duck is plugged in, it broadcats a Wi-Fi acces point network with DUCK-CA:B8:DA:XX:XX:XX SSID'. Use default password to connect to the AP. Your device will launch configuration page in captive portal. If your device does not automatically launch captive portal, navigate to http:\\192.168.4.1 in your default browser.
Once Duck is connected to a network via Wi-Fi or Ethernet, its configuration page can be accessed through its local IP address from the same network. The local IP address is displayed on the home tab of the configuration page and is also shown in the MQTT information message.

Connectivity

Wi-Fi & Ethernet

Duck supports both Wi-Fi and Ethernet for network connections. By default, the network adapter is set to Wi-Fi, but this can be modified in the Settings of the Configuration page Settings > Connectivity.

NTP

Time information is also used in the measurement messages sent by Duck. Time synchronization is needed for this. For OnPremise or private installations, default NTP server can be modified in Duck Configuration page Settings > NTP.
Default: http://pool.ntp.org/

MQTT

Duck needs MQTT / TLS configuration and supports variety of authentication mechanisms including: plaintext MQTT, MQTTs with and without password, and MQTTs with Client certificate.
The MQTT Broker Server to be used must support TLS and provide the following for certificate-based connections:

MQTT endpoint (mqtts: //my-mqtt-broker.server: 8883)
CA (CA certificate)
Client Cert (a created and signed certificate from CA)
Client Key (private key of the certificate generated through the CA)

Required certificates and endpoint information are defined at Settings > MQTT in the Duck configuration page. Duck uses these certificates for the future MQTT connections.

Details https://www.hivemq.com/blog/mqtt-security-fundamentals-tls-ssl/

HTTP

Duck can be controlled over HTTP, allowing for configuration modifications and measurement actions on attached devices. Accessing HTTP endpoints requires an initial login, after which the received token must be used for subsequent communications. Detailed information about HTTP endpoints, including those utilized by the Duck Configuration Web Page, is available in the HTTP Integration section.

Duck Sensor Configuration

Duck is compatible with industry standard 4-20mA sensors. Duck sensor configuration consists of sensor groups. Each group is indented to monitor a single point on an equipment.

Multiple sensors can be grouped in a single sensor group to monitor different characteristics of a point such as temperature and humidity or acceleration and magnetic field.
One sensor can be configured with one or multiple input channels depending on sensor's functionality. For example, distance sensor is configured with a single input channel whereas 3-axis acceleration sensor is configured with 3 input channels for x, y z axes.

Device Config

Explaniation

{
  "heartbeat_interval_min": 15,
  "sensor_groups": [
    {
      "sensor_group_code": "fe1e2714-5ac0-404c-9eb1-20f3a1d2a214",
      "sensors": [
        {
          "sensor": "accelerometer",
          "channels": [0, 1, 2],
          "channel_codes": [
            "accelerometer_x",
            "accelerometer_y",
            "accelerometer_z"
          ],
          "min_max_voltage": [-5, 5],
          "min_max_value": [-1000, 1000],
          "trigger_differancel_rate": 2
        }
      ]
    }
  ]
}

{
  "heartbeat_interval_min": 15,
  "sensor_groups": [
    {
      "sensor_group_code": "fe1e2714-5ac0-404c-9eb1-20f3a1d2a214",
      "sensors": [
        {
          "sensor": "accelerometer",
          "channels": [0, 1, 2],
          "channel_codes": [
            "accelerometer_x",
            "accelerometer_y",
            "accelerometer_z"
          ],
          "min_max_voltage": [-5, 5],
          "min_max_value": [-1000, 1000],
          "trigger_differancel_rate": 2
        }
      ]
    }
  ]
}

MQTT Integration

This section explains which topics to use when communicating with Duck over MQTT and how messages should be interpreted.

Actor sends Payload with PayloadType format to Topic

Information

When Duck powers on, it publishes a status message containing basic device information including Firmware Version. This status message can also be retrieved using the following topic:

Actor

Topic

Payload Type

Payload Schema

Example

User

sensemore/<DuckMac>/info

JSON

Empty JSON

Duck

sensemore/<DuckMac>/info/accepted

JSON

{
  "Product": "Duck",
  "Current Running Application": "<DUCK_VERSION>",
  "Version": "<FIRMWARE_VERSION>",
  "Compile Date": "<FIRMWARE_COMPILE_DATE>",
  "Compile Time": "<FIRMWARE_COMPILE_TIME>",
  "ESP-IDF Version": "<ESPRESSIF_IDF_VERSION>",
  "Network Mode": "<SELECTED_NETWORK_ADAPTOR>",
  "RSSI": <RECEIVED_SIGNAL_STRENTGH_INDICATOR>,
  "Local IP": "<ASSIGNED_LOCAL_IP>",
  "Network MAC": "<NETWORK_MAC_ADDRESS>",
  "Last Reset Reason": "<RESET_REASON>",
  "Runtime MS": <TIME_SINCE_LAST_RESET>,
  "Memory Info": {
    "Total Free Bytes": <STORAGE_CAPACITY>,
    "Total Allocated Bytes": <USABLE_STORAGE>,
    "Min Free Bytes": <MIN_FREE_BTYES>,
    "Largest Free Bytes": <LARGEST_FREE_BYTES>
  }
}

{
  "Product": "Duck",
  "Current Running Application": "Duck-3.0.0",
  "Version": "3.0.0",
  "Compile Date": "Jan 8 2018",
  "Compile Time": "12:00:00",
  "ESP-IDF Version": "v5.1.2",
  "Network Mode": "WIFI",
  "RSSI": -56,
  "Local IP": "192.168.1.153",
  "Network MAC": "00:00:00:00:00:00",
  "Last Reset Reason": "POWERON",
  "Runtime MS": 3244190,
  "Memory Info": {
    "Total Free Bytes": 4084904,
    "Total Allocated Bytes": 384008,
    "Min Free Bytes": 4038248,
    "Largest Free Bytes": 3997696
  }
}

Firmware Update Over the Air (OTA)

Sensemore devices accept firmware update over HTTP. In order to start firmware update on the device, valid binary link sent to firmware update topic. Duck downloads the binary from given url and start firmware update.

Actor	Topic	Payload Type	Payload Schema	Example
User	sensemore/<DuckMac>/ota	JSON	http url	{ "url": "http://link.mydomain.com/Duck.bin" }
Duck	sensemore/<DuckMac>/ota/accepted	JSON	Status JSON	{ "status": "OTA accepted" }
Duck	sensemore/<DuckMac>/ota/rejected	Text	Error Text	Invalid payload! Url can't be null. Valid payload scheme: { "url":"http://link.mydomain.com/Duck.bin" }
Duck	sensemore/<DuckMac>/restart	JSON	Status JSON	{ "status": "Restarting device due to OTA" }

Restart

Duck can be restarted using the following topic.

Actor	Topic	Payload Type	Payload Schema	Example
User	sensemore/<DuckMac>/restart	JSON	Empty JSON

Sensor Configuration

Duck's sensor configuration can be viewed or changed over MQTT with the following topics.

Actor

Topic

Payload Type

Payload Schema

Example

User

sensemore/<DuckMac>/config/get

JSON

Empty JSON

Duck

sensemore/<DuckMac>/config/get/accepted

JSON

Config JSON

{
  "heartbeat_interval_min": 98,
  "sensor_groups": [
    {
      "sensor_group_code": "fe1e2714-5ac0-404c-9eb1-20f3a1d2a214",
      "sensors": [
        {
          "sensor": "accelerometer",
          "channels": [0],
          "channel_codes": ["accelerometer_x"],
          "min_max_voltage": [-5, 5],
          "min_max_value": [-1000, 1000],
          "trigger_differancel_rate": 2
        }
      ]
    }
  ]
}

❗ Changing Duck’s sensor configuration will trigger a restart of the device.

Actor

Topic

Payload Type

Payload Schema

Example

User

sensemore/<DuckMac>/config/set

JSON

Config JSON

{ "heartbeat_interval_min": 15, "sensor_groups": [ { "sensor_group_code": "fe1e2714-5ac0-404c-9eb1-20f3a1d2a214", "sensors": [ { "sensor": "accelerometer", "channels": [0], "channel_codes": ["accelerometer_x"], "min_max_voltage": [-5, 5], "min_max_value": [-1000, 1000], "trigger_differancel_rate": 2 } ] } ] }

Duck

sensemore/<DuckMac>/config/set/accepted

JSON

Status JSON

{ "status": "OK, device will be restarted" }

Measuremnt

Duck device is designed for high-performance data acquisition with multiple ways to trigger measurements. It continuously collects data and evaluates conditions for publishing measurements based on the following mechanisms:
1. Heartbeat: If no measurement has been published within a time period exceeding the configured heartbeat value, Duck automatically publishes a measurement.
2. Trigger Difference: Duck publishes a measurement when the difference between the current and previous measurements exceeds the configured percentage threshold. The Trigger Difference can be adjusted in the device’s configuration settings.
3. Sensemore Lake: Users can send manual measurement requests through the Sensemore Lake platform.
4. MQTT: Manual measurement requests can also be sent via MQTT. Details about the MQTT topics are provided in down below.

Actor

Topic

Payload Type

Payload Schema

Example

User

sensemore/<DuckMac>/device/<DuckMac>/measure/<MEASUREMENT_UUID>

JSON

Empty JSON

Duck

sensemore/<DuckMac>/device/<DuckMac>/measure/<MEASUREMENT_UUID>/accepted

JSON

Status JSON

{ "status": "initiated" }

Duck

sensemore/<DuckMac>/device/<DuckMac>/measure/<MEASUREMENT_UUID>/metadata

JSON

Metadata JSON

{ "measurement_uid": "f86e2b10-6475-42ed-95ab-b37fe24ca888", "calibrated_sampling_rate": 6403, "sampling_rate": 6403, "unixtimestamp": "1734094422", "device-mac": "CA:B8:DA:DE:AD:00", "version": "3.0.0", "reason": "measurement_request", "channel0_rms": 1.504085898399353, "channel1_rms": -1, "channel2_rms": -1, "channel3_rms": -1, "channel4_rms": -1, "channel5_rms": -1, "channel6_rms": -1, "channel7_rms": -1, "config": { "heartbeat_interval_min": 98, "sensor_groups": [ { "sensor_group_code": "fe1e2714-5ac0-404c-9eb1-20f3a1d2a214", "sensors": [ { "sensor": "accelerometer", "channels": [0], "channel_codes": ["accelerometer_x"], "min_max_voltage": [-5, 5], "min_max_value": [-1000, 1000], "trigger_differancel_rate": 2 } ] } ] } }

HTTP Integration

Duck offers extensive HTTP endpoints for retrieving or modifying settings on Duck and its attached devices.

Some endpoints require an authentication token in the header. Endpoints requiring an authentication token in the header are marked with the 🔐 symbol.
This token is obtained using the Login endpoint, as shown below:

Login

Method	Endpoint	Content-Type	Example
POST	/login	application/json	{ "password": "<DEFAULT_PASSWORD>" }
GET	/login	application/json	{ "token": "CLjziyTeTzlMsv100mvgkxnTQl1nGYXpQvsIStAW16WrMjxzLvhNTOGhcFFzU38mT8sHKFhxBOm3309qxSmzKIHJux3rUbjVTkywmayA1O05hKaQn9jlY99YMmp1NorF" }

Include your token in the Header

Once the authentication token is obtained via the Login endpoint, it must be included in the header of each HTTP request for 🔐 endpoints, as shown below.

{
  "Authorization": "CLjziyTeTzlMsv100mvgkxnTQl1nGYXpQvsIStAW16WrMjxzLvhNTOGhcFFzU38mT8sHKFhxBOm3309qxSmzKIHJux3rUbjVTkywmayA1O05hKaQn9jlY99YMmp1NorF"
}

Logout

Method	Endpoint	Content-Type	Example
POST	/logout	application/json

Information

Basic information about the device, including its Firmware Version, can be retrieved using the following HTTP endpoint:

Method	Endpoint	Content-Type	Example
GET	/info	application/json	{ "mac_address": "CA:B8:DA:XX:XX:XX", "version": "3.0.0", "is_network_connected": true, "is_internet_connected": true }

🔐 Change Password

The device’s HTTP and web configuration interface password can be changed using the following HTTP endpoint:

Method	Endpoint	Content-Type	Example
PUT	/change_password	application/json	{ "old_password": "<DEAFULT_PASSWORD>", "new_password": "12345678" }

🔐 NTP

Time information is part the measurement messages sent by Duck. NTP configuration can be retrieved or modified using the following HTTP endpoint:

Method	Endpoint	Content-Type	Example
GET	/sntp	application/json	{ "sntp_server": "http://pool.ntp.org/" }
POST	/sntp	application/json	{ "sntp_server": "http://pool.ntp.org/" }

🔐 Firmware Update Over the Air (OTA)

Method	Endpoint	Content-Type	Example
POST	/ota	application/octet-stream	{}

🔐 Restart

Duck can be restarted using the following endpoint.

Method	Endpoint	Content-Type	Example
GET	/restart	application/json

🔐 Measurement Upload URL

Duck manages measurement uploads for attached devices by publishing metadata over MQTT and transmitting signal binaries via HTTP.
The default binary upload URL is https://core.sensemore.io/measurement/, however, the URL can be retrieved or modified using the following endpoint.

Method	Endpoint	Content-Type	Example
GET	/binary-url	application/json	{ "url": "https://core.sensemore.io/measurement" }
POST	/binary-url	application/json	{ "url": "https://core.sensemore.io/measurement" }

🔐 Sensor Configuration

Duck's sensor configuration can be viewed or changed over HTTP with the following endpoints.

Method

Endpoint

Content-Type

Example

GET

/configuration

application/json

{ "heartbeat_interval_min": 98, "sensor_groups": [ { "sensor_group_code": "fe1e2714-5ac0-404c-9eb1-20f3a1d2a214", "sensors": [ { "sensor": "accelerometer", "channels": [0], "channel_codes": ["accelerometer_x"], "min_max_voltage": [-5, 5], "min_max_value": [-1000, 1000], "trigger_differancel_rate": 2 } ] } ] }

POST

/configuration

application/json

{ "heartbeat_interval_min": 98, "sensor_groups": [ { "sensor_group_code": "fe1e2714-5ac0-404c-9eb1-20f3a1d2a214", "sensors": [ { "sensor": "accelerometer", "channels": [0], "channel_codes": ["accelerometer_x"], "min_max_voltage": [-5, 5], "min_max_value": [-1000, 1000], "trigger_differancel_rate": 2 } ] } ] }

❗ Changing Duck’s sensor configuration will trigger a restart of the device.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

duck.md

duck.md

Duck Integration Document

Accessing Configuration Page

Connectivity

Wi-Fi & Ethernet

NTP

MQTT

HTTP

Duck Sensor Configuration

MQTT Integration

Information

Firmware Update Over the Air (OTA)

Restart

Sensor Configuration

Measuremnt

HTTP Integration

Login

Include your token in the Header

Logout

Information

🔐 Change Password

🔐 NTP

🔐 Firmware Update Over the Air (OTA)

🔐 Restart

🔐 Measurement Upload URL

🔐 Sensor Configuration

Files

duck.md

Latest commit

History

duck.md

File metadata and controls

Duck Integration Document

Accessing Configuration Page

Connectivity

Wi-Fi & Ethernet

NTP

MQTT

HTTP

Duck Sensor Configuration

MQTT Integration

Information

Firmware Update Over the Air (OTA)

Restart

Sensor Configuration

Measuremnt

HTTP Integration

Login

Include your token in the Header

Logout

Information

🔐 Change Password

🔐 NTP

🔐 Firmware Update Over the Air (OTA)

🔐 Restart

🔐 Measurement Upload URL

🔐 Sensor Configuration