IoT Device pairing with application

Overview of concepts and best practices for pairing IoT devices with application.

Every Device Type that has decoder gets default base for code which follows convention

[device_manufacturer_company]-[device-model-name-and-potential-version]-[firmware-version]

Example of default base code for Senzemo Senspuck SPU10B

sensedge-senspuck-spu10b-v001

---

Naming convention schemas recommendations

It’s highly recommended that you define strict and well-described naming conventions for your different device types which are in use inside your tenant!

Well-defined naming convention saves a lot of time when establishing IoT sensor ecosystem for your tenant and prevents debugging why there is no decoded data for specific device in application.

Few examples of good naming convention schemas for specific device:

[device_manufacturer_company]-[device-model-name-and-potential-version]-[sequence-number]
[device_manufacturer_company]-[device-model-name-and-potential-version]-[serial-number]

Tip

It’s recommended that firmware version is not part of naming convention scheme for production installed device.
When device is flashed with new major firmware version, device name remains the same.
It’s also a misleading name if there is a different firmware version in a specific device name as it is.

Tip

It’s highly recommended that there are no UNDERSCORE characters (_) inside specific device name!

Instead of underscore, use hyphen/dash (-) or at sign (@) (preferred hyphen/dash).
Avoid also space characters in favor of hyphen/dash.

Some network concentrators do not even allow underscore characters (like The Things Stack).

Some reverse proxies (like nginx) recogize underscore as special characters. https://nginx.org/en/docs/http/ngx_http_core_module.html#ignore_invalid_headers https://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headers

Tip

Don’t mix uppercase and lowercase letters.
Decide for lowercase or uppercase and stick with that for the whole defined naming convention.

Caution

Application does not allow inserting specific custom-defined pairing code base if this character string is already sub-string inside other pairing code base string (on this or any other Device Type).

Automatic device recognition

If devices are named by conventions, automatic device recognition is possible.

It is recommended that sequence or device serial number is appended to the end of specific device name that automatic device recognition works.

Example for specific device name for device type Senzemo Senspuck SPU10B based on default code:

sensedge-senspuck-spu10b-v001-0000025

Instead of sequence number, you can use serial number or something different that is unique. Example:

sensedge-senspuck-spu10b-v001-[serial-number]
or
sensedge-senspuck-spu10b-v001-[custom-unique-word]

---

Decoding processing logic in the application recognizes device type sensedge-senspuck-spu10b-v001 without any doubts and therefore also payload decoding logic.

Caution

Device unique name inside tenant

For specific device name (like sensedge-senspuck-spu10b-v001-0000025) is not guaranteed that is 100% unique in application!

Specific devices are uniquely determined by Network Concentrator instance id/name and specific device name.

Reasons for such design decision: It is not possible to prevent that one specific device (with specific name) is connected to multiple network concentrators (more specific instances of network concentrators) and configured that all network concentrators with this specific device forward data to the same tenant in the application.

Caution

Major device type firmware updates

Sometimes specific device type receives major firmware update, which changes the payload structure.
Therefore, some device types have multiple versions, which are defined on Supported IoT Devices page with different default pairing code base.

Specific Device Type with a major firmware update (with a different payload structure compared to the previous firmware version) is treated as a new Device Type.

---

Applying additional pairing code base for Device Type

It is possible to assign one or more different pairing code bases for specific Device Type.

Tip

It’s recommended that for the production environment (when IoT devices are installed on real locations) custom naming scheme is defined without firmware version data and applied on relevant Device Types before first IoT devices send data.

When assigning a new pairing code base for device type consider:

• Read and follow Naming convention schemas recommendations
• Define only one naming convention scheme if possible
• Be consistent with the naming scheme!

---

Updating major firmware version in production environment

When updating firmware (major version) of installed IoT devices (based on specific Device Type), it is MANUAL JOB to change Device Type on specific devices to different device type.

Caution

Updating all devices with new (major) firmware version take some time.
Therefore, changing device type on specific device manually is mendatory operation when specific device is updated with new firmware verison.

The only case, when automatic update of device type on specific device is executed when device type of specific device is unknown. When such device receives message in application and device type can be determined - it is assigned and never automatically changed.

Correst order of steps when updating firmware for specific device type:

1. If there are custom pairing code bases on old device type, delete them and create identical ones on new device type.
2. Based on firmware updating status of specific devices, update device type manually in application for these specific devices.

Danger

During firmware update process (time range), some received messages (payloads) may not be decoded properly due to mismatch of payload message and defined device type on specific device in application.