Senseway Integration Documentation

Senseway is a gateway for Wired Pro, Infinity, Infinity Pro and Nomad sensors. Senseway handles networking, measurement scheduling, sleep, firmware update and more for Sensemore sensors.

The data acquisition devices page covers the Senseway hardware. For an installation guide, get in touch.

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

Accessing Configuration Page

Shortly after the Senseway is plugged in, it broadcasts a Wi-Fi access point network with SENSEWAY-CA:B8:50: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 Senseway 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

Senseway 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 Senseway. Time synchronization is needed for this. For OnPremise or private installations, default NTP server can be modified in Senseway Configuration page Settings > NTP.
Default: http://pool.ntp.org/

MQTT

Senseway 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 Senseway configuration page. Senseway uses these certificates for the future MQTT connections.

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

HTTP

Senseway 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 Senseway Configuration Web Page, is available in the HTTP Integration section.

MQTT Integration

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

Actor sends Payload with PayloadType format to Topic

Information

When Senseway 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:

{
  "Product": "Senseway",
  "Current Running Application": "<SENSEWAY_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": "Senseway",
  "Current Running Application": "SENSEWAY-3-0-0",
  "Version": "3.0.0",
  "Compile Date": "Jan 8 2018",
  "Compile Time": "12:00:00",
  "ESP-IDF Version": "v5.1.4",
  "Network Mode": "WIFI",
  "RSSI": -73,
  "Local IP": "192.168.1.111",
  "Network MAC": "00:00:00:00:00:00",
  "Last Reset Reason": "POWERON",
  "Runtime MS": 281440,
  "Memory Info": {
    "Total Free Bytes": 4034708,
    "Total Allocated Bytes": 403896,
    "Min Free Bytes": 4024696,
    "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. Senseway downloads the binary from given url and start firmware update.

{
  "url": "http://link.mydomain.com/Senseway.bin"
}

{
  "status": "OTA accepted"
}

{
  "status": "Restarting device due to OTA"
}

Restart

Senseway can be restarted using the following topic.

Measurement Upload URL

Senseway 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 topic.

{
  "binaryurl": "https://core.sensemore.io/measurement"
}

{
  "binaryurl": "https://core.sensemore.io/measurement"
}

{
  "status": "Set Binary url accepted",
  "binaryurl": "https://core.sensemore.io/measurement"
}

Senseway - Wired Pro Communication Speed

Senseway communicates with Wired Pro over RS485, which has a theoretical range of up to one kilometer. This allows Senseway and Wired Pro to be placed up to 1 km apart and connected via an RS485 cable. As the distance between them increases, the baudrate must be lowered to increase reliability. Baudrate refers to the number of bits transmitted per second. At shorter distances, increasing the baudrate can increase communication speed between Senseway and Wired Pro. The baudrate can be viewed or modified via MQTT using the following topic.

:warning: When connecting multiple Wired Pros to the same Senseway, a bus topology must be used, ensuring no parallel lines are present.

{
  "baudrate": 921600
}

Valid badurate values: 115200, 460800, 921600, 1000000

{
  "baudrate": 921600
}

{
  "status": "Set baud rate accepted",
  "baudrate": 921600
}

Device List

The list of devices attached to Senseway, along with their measurement configurations, can be retrieved using the following topic.

{
  "devices": [
    {
      "mac": "CA:B8:41:XX:XX:XX",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    },
    {
      "mac": "CA:B8:30:XX:XX:XX",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    }
  ]
}

Senseway evaluates the connection status of each assigned sensor upon receiving a scan command. It then publishes a result message that includes the Firmware Version of each connected device.

:warning: Infinity, Infinity Pro and Nomad may appear as “not scanned” if they are on sleeping schedule.

{
  "devices": [
    {
      "mac": "CA:B8:41:XX:XX:XX",
      "status": "connected",
      "version": "2.1.14",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    },
    {
      "mac": "CA:B8:30:XX:XX:XX",
      "status": "scanned",
      "rssi": -58,
      "version": "3.0,0",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    }
  ]
}

Device Firmware Update Over The Air (OTA)

Sensemore end node devices accept firmware update over HTTP. In order to start firmware update on end-node device, valid binary link sent to firmware update topic. Senseway downloads the binary from given url and start firmware update for particular device.

{
  "url": "http://link.mydomain.com/Device.bin"
}

{
  "status": "OTA accepted"
}

Device Add & Remove

The devices attached to Senseway can be viewed or modified using the following topics.

{
  "mac": "CA:B8:XX:XX:XX:XX"
}

{
  "status": "Device added"
}

{
  "mac": "CA:B8:XX:XX:XX:XX"
}

{
  "status": "Device removed"
}

Device Measurement Configuration

Senseway is compatible with both wired sensors (Wired Pro) and wireless sensors (Infinity, Infinity Pro, Nomad). Wireless sensors typically utilize a sleep schedule feature to extend their battery life, allowing for operation of up to 2 years on a single charge.

{
  "device_mac": "CA:B8:XX:XX:XX:XX",
  "device_config": {
    "rs485_resistor_enabled": false,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": 1,
    "scheduler_enabled": false,
    "trigger_enabled": false
  }
}

{
  "device_mac": "Device ID",
  "device_config": {
    "rs485_resistor_enabled": Termination resistor, only applicable to Wired Pro,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": [1 for accelerometer, 0 for unkown devices],
    "scheduler_enabled": Periodic measurement & sleep schedule for Infinity family devices,
    "trigger_enabled": Senseway tigger number for a perticular device
  }
}

The configuration of a specific device can be retrieved using the following topic.

{
  "device_mac": "CA:B8:XX:XX:XX:XX",
  "device_config": {
    "rs485_resistor_enabled": false,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": 1,
    "scheduler_enabled": false,
    "trigger_enabled": false
  }
}

The configuration of a specific device can be modified using the following topic.

{
  "device_config": {
    "rs485_resistor_enabled": false,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": 1,
    "scheduler_enabled": false,
    "scheduler_period": false,
    "trigger_enabled": false,
    "trigger_pin": false
  }
}

{
  "device_config": {
    "rs485_resistor_enabled": false,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": 1,
    "scheduler_enabled": false,
    "scheduler_period": false,
    "trigger_enabled": false,
    "trigger_pin": false
  },
  "status": "Device config updated",
  "mac": "End Node Mac"
}

Measurement

Senseway initiates automatic measurement using the scheduling feature. It also accepts manual measurements from the Sensemore Lake platform as well as  MQTT based on the configurations set previously. MQTT measurement topics are as follows.

{
  "status": "Measurement started"
}

{
  "status": "Measurement done"
}

{
  "unixtimestamp": 1734443808,
  "calibrated_sampling_rate": 26746,
  "temperature": 22.719999313354492,
  "battery_voltage": 4.0489997863769531,
  "sampling_rate": 25600,
  "sample_size": 50000,
  "accelerometer_range": 16,
  "measurement_type": 1,
  "measurement_buffer_size": 300000
}

HTTP Integration

Senseway offers extensive HTTP endpoints for retrieving or modifying settings on Senseway 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

{
  "password": "<DEFAULT_PASSWORD>"
}

{
  "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

Information

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

{
  "mac_address": "CA:B8:50:XX:XX:XX",
  "version": "3.1.9",
  "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:

{
  "old_password": "<DEAFULT_PASSWORD>",
  "new_password": "12345678"
}

🔐 NTP

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

{
  "sntp_server": "http://pool.ntp.org/"
}

{
  "sntp_server": "http://pool.ntp.org/"
}

🔐 Firmware Update Over the Air (OTA)

🔐 Restart

Senseway can be restarted using the following endpoint.

🔐 Measurement Upload URL

Senseway 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.

{
  "url": "https://core.sensemore.io/measurement"
}

{
  "url": "https://core.sensemore.io/measurement"
}

🔐 Senseway - Wired Pro Communication Speed

Senseway communicates with Wired Pro over RS485, which has a theoretical range of up to one kilometer. This allows Senseway and Wired Pro to be placed up to 1 km apart and connected via an RS485 cable. As the distance between them increases, the baudrate must be lowered to increase reliability. Baudrate refers to the number of bits transmitted per second. At shorter distances, increasing the baudrate can increase communication speed between Senseway and Wired Pro. The baudrate can be viewed or modified via HTTP using the following endpoint.

:warning: When connecting multiple Wired Pros to the same Senseway, a bus topology must be used, ensuring no parallel lines are present.

{
  "baudrate": 921600
}

{
  "baudrate": 921600
}

Valid badurate values: 115200, 460800, 921600, 1000000

🔐 Device List

The list of devices attached to Senseway, along with their measurement configurations, can be retrieved using the following endpoint.

{
  "count": 2
}

{
  "devices": [
    {
      "mac": "CA:B8:41:XX:XX:XX",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    },
    {
      "mac": "CA:B8:30:XX:XX:XX",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    }
  ]
}

Senseway evaluates the connection status of each assigned sensor upon receiving a scan command. It then sends a result message that includes the Firmware Version of each connected device.

:warning: Infinity, Infinity Pro and Nomad may appear as “not scanned” if they are on sleeping schedule.

{
  "devices": [
    {
      "mac": "CA:B8:41:XX:XX:XX",
      "status": "connected",
      "version": "2.1.14",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    },
    {
      "mac": "CA:B8:30:XX:XX:XX",
      "status": "scanned",
      "rssi": -58,
      "version": "3.0,0",
      "device_config": {
        "rs485_resistor_enabled": false,
        "trigger_enabled": false,
        "accelerometer_range": 16,
        "sampling_rate": 25600,
        "sample_size": 50000,
        "sensor_type": 1,
        "scheduler_enabled": false
      }
    }
  ]
}

🔐 Device Firmware Update Over The Air (OTA)

{}

🔐 Device Add & Remove

The devices attached to Senseway can be viewed or modified using the following endpoints.

{
  "mac": "CA:B8:XX:XX:XX:XX"
}

{
  "mac": "CA:B8:XX:XX:XX:XX"
}

🔐 Device Measurement Configuration

Senseway is compatible with both wired sensors (Wired Pro) and wireless sensors (Infinity, Infinity Pro, Nomad). Wireless sensors typically utilize a sleep schedule feature to extend their battery life, allowing for operation of up to 2 years on a single charge.

{
  "device_mac": "CA:B8:XX:XX:XX:XX",
  "device_config": {
    "rs485_resistor_enabled": false,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": 1,
    "scheduler_enabled": false,
    "trigger_enabled": false
  }
}

{
  "device_mac": "Device ID",
  "device_config": {
    "rs485_resistor_enabled": Termination resistor, only applicable to Wired Pro,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": [1 for accelerometer, 0 for unkown devices],
    "scheduler_enabled": Periodic measurement & sleep schedule for Infinity family devices,
    "trigger_enabled": Senseway tigger number for a perticular device
  }
}

The configuration of a specific device can be retrieved using the following topic.

{
  "device_mac": "CA:B8:XX:XX:XX:XX",
  "device_config": {
    "rs485_resistor_enabled": false,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": 1,
    "scheduler_enabled": false,
    "trigger_enabled": false
  }
}

{
  "device_mac": "CA:B8:XX:XX:XX:XX",
  "device_config": {
    "rs485_resistor_enabled": false,
    "accelerometer_range": 16,
    "sampling_rate": 25600,
    "sample_size": 50000,
    "sensor_type": 1,
    "scheduler_enabled": false,
    "trigger_enabled": false
  }
}

🔐 Measurement

Senseway initiates automatic measurement using the scheduling feature. It also accepts manual measurements from the Sensemore Lake platform as well as MQTT & HTTP based on the configurations set previously. HTTP measurement endpoints are as follows.

{
  "mac": "CA:B8:XX:XX:XX:XX"
}