IoT & Telemetry

IoT & Telemetry

Nekazari ingests sensor data through the FIWARE IoT Agent JSON over MQTT. Devices publish lightweight JSON payloads; the platform translates them into semantically rich NGSI-LD entities using Smart Data Models.

Architecture

Datalogger / Sensor
       │
       ▼  MQTT (JSON payload)
   Mosquitto Broker
       │
       ▼  /<apikey>/<device_id>/attrs
   IoT Agent JSON (NGSI-LD native)
       │  explicitAttrs: true
       ▼  Only profiled attributes pass
   Orion-LD Context Broker
       │
       ▼  NGSI-LD subscription
   Telemetry Worker → TimescaleDB

DeviceProfile (mandatory)

Every IoT sensor must have a DeviceProfile before provisioning. The profile defines how raw datalogger keys map to standard SDM attributes.

Field	Description
incoming_key	Key sent by the datalogger over MQTT (e.g. t_ext)
target_attribute	SDM attribute in Orion-LD (e.g. airTemperature)
type	Data type (Number, Text)
transformation	Optional JEXL expression (e.g. val * 0.1)

Example profile

{
  "name": "Agrivoltaic Station",
  "sdm_entity_type": "AgriSensor",
  "mappings": [
    { "incoming_key": "airTemperature", "target_attribute": "airTemperature", "type": "Number" },
    { "incoming_key": "solarRadiation", "target_attribute": "solarRadiation", "type": "Number" },
    { "incoming_key": "relativeHumidity", "target_attribute": "relativeHumidity", "type": "Number" },
    { "incoming_key": "soilMoisture", "target_attribute": "soilMoisture", "type": "Number" }
  ]
}

Profiles can be created in the platform UI, imported as JSON, or auto-generated by DaTaK gateways.

Provisioning flow

1. Create a DeviceProfile with attribute mappings for your datalogger
2. Create a sensor in the Entity Wizard — select the profile (mandatory)
3. Copy MQTT credentials shown after creation (displayed once, not recoverable)
4. Configure the datalogger with the MQTT host, port, topic, and credentials

The platform stores refDeviceProfile as an NGSI-LD Relationship on the entity. Key regeneration preserves the profile mapping.

MQTT protocol

Property	Value
Broker	Mosquitto (TLS on port 8883, plain on 31883)
Topic	/<tenant_apikey>/<device_id>/attrs
Payload	{"attributeName": value} (flat JSON)
Auth	Username + password (from provisioning)

# Example publish
mosquitto_pub -h nkz.robotika.cloud -p 31883 \
  -u <username> -P <password> \
  -t "/<apikey>/<device_id>/attrs" \
  -m '{"airTemperature": 22.5, "solarRadiation": 450}'

Strict SDM enforcement

The IoT Agent runs with IOTA_EXPLICIT_ATTRS=true. Only attributes declared in the DeviceProfile reach Orion-LD. Undeclared MQTT keys are silently dropped. This guarantees that the digital twin only contains validated, standards-compliant data.

DaTaK integration

DaTaK is an open-source edge gateway that collects local sensor data (Modbus, CANbus, MQTT) and publishes it to Nekazari. It includes:

• Smart Auto-SDM Mapping: infers SDM attribute names from sensor names (e.g. “Piranometro solar” becomes solarRadiation)
• Profile generation: GET /api/config/device-profile returns a JSON profile ready to import into the platform wizard
• Offline resilience: buffers data locally when connectivity is lost

Configure the digital_twin section in configs/gateway.yaml with the MQTT credentials from the wizard.

Supported SDM attributes (AgriSensor)

Attribute	Description	Unit
airTemperature	Air temperature	CEL
relativeHumidity	Relative humidity	P1 (%)
atmosphericPressure	Atmospheric pressure	HPA
solarRadiation	Solar radiation	W/m2
windSpeed	Wind speed	m/s
windDirection	Wind direction	DD
precipitation	Precipitation	mm
soilMoisture	Soil volumetric water content	P1 (%)
soilTemperature	Soil temperature	CEL
leafTemperature	Leaf temperature	CEL
photosyntheticallyActiveRadiation	PAR	umol/m2s
panelTemperature	PV panel temperature	CEL
energyProduction	Energy production	kWh
batteryLevel	Battery level	P1 (%)