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.

Sender allowlist and rate limit

UDP has no login, so the platform checks where each packet comes from:

• Sender allowlist. The platform can accept packets only from a list of sender IP addresses and ranges. Packets from any other address are dropped and logged. The list is set on the server by the network administrator, not in the platform: on hosted platforms ask Sensative support, on your own installation ask your network administrator. When no list is set, packets from every address are accepted.
• Rate limit. Each sender IP address may send up to 100 packets per second by default. Packets over the limit are dropped and logged. Packets from other addresses are not affected.

When the devices use NB-IoT or Cat-M, their packets reach the platform from the mobile operator's network, so the allowlist must contain the operator's address ranges, not the devices' own addresses. Ask the operator for them. For the same reason the rate limit covers all devices behind one operator address together, so size it for the whole fleet: 3,000 devices that each report once a minute send 50 packets per second.

For network administrators

Set the allowlist and the rate limit in the udp section of the UDP service's config.json:

"udp": {
  "allowedSenders": ["198.51.100.0/24", "203.0.113.7"],
  "maxPacketsPerSecondPerSender": 100,
  "allowedPorts": [12012]
}

Or with environment variables on the UDP service, which take precedence over config.json:

UDP_ALLOWED_SENDERS=198.51.100.0/24,203.0.113.7
UDP_MAX_PACKETS_PER_SECOND_PER_SENDER=100
UDP_ALLOWED_PORTS=12012

Each entry is an IPv4 address or an IPv4 range with a prefix length. The service refuses to start with an entry it cannot read. Without an allowlist, the service logs a warning when it starts.

allowedPorts lists the UDP ports the firewall lets through. A UDP connector set to any other port is not started, and the service logs that it was refused. Without allowedPorts, connectors may use any port from 1025 to 65535.

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 drops the message and logs it. It does not create a device, so data the device sends before these steps are done is lost.

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 Step 3 fails with a duplicate error

Older platform versions created a hidden device when a message arrived for an identifier that no device had. If the physical device reported to such a version before these steps were done, that hidden device still holds the 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.