UDP Connector

Connector Details – UDP

The UDP connector allows the platform to receive device updates over the UDP protocol. This is typically used by devices communicating via NB-IoT, Cat-M, or similar wireless technologies, though direct wired UDP connections are also supported.

Incoming data must be a HEX-encoded string that includes an embedded identifier to determine the source device.

Required Information

To configure a UDP connection, the following must be provided:

• Integration name
  Specifies how the platform processes and validates incoming UDP data. It identifies the type of device sending the data and ensures correct matching on the platform.

• Port number
  The UDP port where the platform listens for incoming data.

Important:
All UDP ports are closed by default. A support request must be submitted to open the desired port.
There are 65,536 available UDP ports (1025 to 65535 are valid numbers).

Security Considerations

UDP data is transmitted unencrypted and can be intercepted once it travels over public networks.
Even though the payload is HEX-encoded, it is not secure by default.

Do not use UDP-only communication for sensitive data over public networks.

To secure the data, the platform supports DTLS (Datagram Transport Layer Security). DTLS can be enabled if the connected IoT devices also support it.

Physical UDP Device Configuration

When setting up the physical UDP device, configure the following on the device:

• The platform’s URL or static IP address
• The UDP port number opened for the connector

You can verify the platform's IP address via a domain lookup service. The IP is static and does not change.
Make sure the port configured in the device exactly matches the connector’s port.

When using NB-IoT or Cat-M, make sure to record the SIM card’s IMSI number so it can be assigned to the correct device in the platform at a later stage.

Creating UDP Devices

A UDP device cannot be created in one step in the single-mode device wizard. You create a Generic device, then give it the identifier the integration matches on, then attach it to the UDP connector. The steps below do that for one device.

For more than one device, Batch install does all three in one upload: choose Generic as the device type, and give each row a secret, a sensorId, and your UDP connector's id in the connector column. The devices are created with their identifier and connector already in place, with no Swagger step.

Important:
Complete every step below before the physical device is activated, meaning before it is powered on or sends its first message. When a message arrives and no device matches both the connector and the identifier, the platform creates a new device on its own. That device belongs to the platform's internal service user, so you cannot see it, and your own device receives no data.

Step 1: Create a Generic device

1. Navigate to Devices, click New device and choose Single mode.
2. Select Generic as the device type.
3. Enter any secret of at least 8 characters. The UDP connector does not use it, but the Generic device type requires one.
4. Finish the wizard as usual. Select the translator for the device on the Translator step, for example imbuildings.

Step 2: Set the identifier in Swagger

The identifier cannot be set from the device page, so set it through the API. Log in to Swagger, find the device's _id, and update the device with PUT /api/iotnodes/{_id}:

{
  "sensorId": "<identifier, exactly as the device sends it>"
}

The field name depends on the integration:

Integration Name	Identifier field	Value
IMBuildings	sensorId	Bytes 3 to 10 of the payload, meaning the 16 hex characters after the first 4, in lowercase

The value must match what the device sends character for character. The comparison is exact, so a single wrong character, or uppercase where the device sends lowercase, means no match.

For example, an IMBuildings payload starting 02060004A30B00ED93F8… has the device type (02) and variant (06) first, followed by the 8-byte device ID, so sensorId is 0004a30b00ed93f8.

Step 3: Attach the UDP connector

1. Navigate to Devices and open Select many.
2. Select the device, or all the devices you have prepared.
3. Choose Set Connector and select your UDP connector.

The device now matches on both the connector and the identifier. Activate the physical device only now.

The steps above are for IMBuildings, but any device reporting through the UDP connector needs the same treatment: a Generic device, the integration's identifier field set to the exact value the device sends, and the UDP connector attached, all before the first message arrives.

If the device has already reported

If the physical device sent data before these steps were done, the platform has already created a hidden device holding that connector and identifier. Each connector and identifier pair can belong to only one device, so Step 3 then fails with a duplicate error, and your own device cannot take over the pair.

The hidden device belongs to the platform's internal service user and cannot be deleted from the interface. Contact Sensative support with the connector and the identifier, and ask for the hidden device to be removed. Then repeat Step 3.

SIM card checks

If NB-IoT or Cat-M is used, make sure to add the SIM card's IMSI number to the device's contextual parameters in the platform.

If no data is received, it’s important to know which SIM card the device is using. This allows you to verify in the SIM provider’s portal that:

• The SIM is active
• Data traffic is correctly routed through the expected APN - Access Point Name

Data Format & Translation

The received data must be a HEX string.
A translator must be selected or created to decode the data and assigned to the UDP device configuration.