Skip to main content

MQTT Device Integration

tip

All types of devices can be integrated into the Neuron platform via MQTT.

Your device will send data via an MQTT Server, and the Neuron platform will subscribe to device data based on the MQTT Server and Topic configuration. Therefore, you need to correctly configure the MQTT Server and Topic beforehand. The Payload in the Topic must include real-time data for each device point. Ensure that the point names (name) in the Payload match the Function Type names in the Neuron platform Device Twins (case-insensitive); otherwise, the platform will not recognize the corresponding data.

MQTT

Pre-configuration​

Devices integrated via MQTT must confirm or configure the following:

  1. MQTT Server
  2. Topic
  3. Device reported data format

1. Configure MQTT Server​

In the left menu, click MQTT Management - MQTT Server to view the existing MQTT servers in the system. Click the Add button to add your MQTT server.

MQTT_List

Fill in the MQTT server information:

  • Name: Must be unique, required
  • Host/Port: Enter according to MQTT server information, required
  • Username/Password: Fill if applicable
  • Status: Enabled

MQTT_Server_ADD

2. Configure Topic​

In the left menu, click MQTT Management - Topic to view the existing topics in the system. Click the Add button to add a new topic.

topic

Fill in the topic information

topic_add

  • Name: Must be unique, required
  • MQTT Server: Select the MQTT server used. If not present, you must add it first (see above).
  • ETL Type: Required, select the data type (IoT/BMS/OpenAPI, etc.). For example, if it's an IoT device, choose IOT_DATA; for BMS devices, choose BMS_API; for openAPI, choose openAPI.
    • ETL_Type
    • ETL_Type_JSON
    • After selection, check if the JSON format below matches the device's reported data format. The system will subscribe to and parse this JSON according to the MQTT server information. If the format does not match, device integration will fail, and you need to select/add an ETL converter (see 3. ETL Converter).
    • ETL_Converter_check
  • Status: Enabled
  • ETL Converter: If the default JSON format does not match your device, you need to add and select your ETL converter (see 3. ETL Converter).

3. Configure ETL Converter​

Configure the device's reported data JSON format.

In the left menu, click System Settings - ETL Converter to view the existing ETL converters in the system. Click the Add button to add a new ETL converter.

ETL_Converter

Fill in the ETL converter information

Add_Data_Converter

  • Name: Must be unique, required
  • Type: IoT/Non IoT
  • Payload content: Device's reported data in JSON format, required
  • Device ID key: Match the unique ID in JSON used to identify the device, typically Device ID / DevEUI, required
  • Device points object key: Match the device's data point in JSON, required
  • Date key: Match the timestamp in JSON
  • Device name key: Match the device name for display in the platform
  • Device location key: Match the location info for the device in the platform
  • Status: Enabled

For detailed operations, refer to 【ETL Converter】.

Start Device Integration into the Platform​

1. Choose Integration Method​

In the Device Management List Page, click the "Add" button to start the device integration process.

device_list

Select MQTT as the integration method, then click Next.

deviceAccess

2. Choose Data Reporting Format​

Device data reporting must adhere to strict format matching rules. The system will subscribe and parse the data based on the configured MQTT server information. If the selected reporting JSON format does not match the actual reporting format, device integration will fail. You will need to choose/add an ETL converter (see ETL Converter).

Choose a Pre-configured Format​

The list will display pre-configured formats. After selecting a matching format, click Next to configure the device twin.

mqtt_dataFormat_default

Choose an Already Created ETL Converter​

If your device reporting format does not match the system's pre-configured format, you need to choose/add an ETL converter. The system will parse the data based on the selected converter's format.

Switch to the Converter panel and select an already created ETL converter.

mqtt_dataFormat_converter

To add a new ETL converter, refer to 【ETL Converter】.

3. Configure Device Twins​

tip

Device Twins Definition: In the Neuron platform, a collection of devices with similar capabilities or characteristics is referred to as a device twin. For more information, refer to 【Device Twins Management】.

You can either choose an existing device twin or create a new device twin.

Choose an Existing Device Twin​

After selecting the desired device twin, click Next to proceed to the device registration page.

You can quickly search by device model name/type/brand.

mqtt_check_device_twins

Add New Device Twin​

Click the Add New Device Twin button, fill in the device twin information, and click "Submit" to create the device twin.

mqtt_add_device_twins

Note: The device twin name must be unique. The system will verify its uniqueness during submission. If the name already exists, the addition will fail.

Configure Function Types (Points)​

After successfully creating the device twin, you can directly configure Function Types under this twin.

Click the “Plus” button to enter the Function Type creation page.

lora_add_device_twins_functions

Click the Function Type input box, select/add a Function Type. For further configuration details, refer to 【Device Twins Management】.

lora_adding_device_twins_functions

If the device twin has multiple Function Types, repeat the steps to add more. After configuration, click Next to proceed to the device registration page.

mqtt_added_device_twins_functions

4. Choose Topic​

The Neuron platform will subscribe to device data based on the configured MQTT server and topic. Therefore, you need to correctly configure the MQTT server and topic used.

Choose an Existing Topic​

After selecting the desired topic, click Next to proceed to the device registration page.

You can quickly search by name.

mqtt_add_device_networkServer

Add New Topic​

Fill in the topic information

topic_add

  • Name: Must be unique, required
  • MQTT Server: Select the MQTT server used. If not present, you must add it first (see above).
  • ETL Type: Required, select the data type (IoT/BMS/OpenAPI, etc.). For example, if it's an IoT device, choose IOT_DATA; for BMS devices, choose BMS_API; for openAPI, choose openAPI.
    • ETL_Type
    • ETL_Type_JSON
    • After selection, check if the JSON format matches the device's reported data format. The system will subscribe to and parse this JSON. If it doesn't match, device integration will fail, and you will need to select/add an ETL converter.
    • ETL_Converter_check
  • Status: Enabled
  • ETL Converter: If the default JSON format does not match your device, you need to add and select your ETL converter (see ETL Converter).

After configuration, click Next to proceed to the device registration page.

5. Device Registration​

Two input methods are supported: Online Editing or Batch Excel Upload.

Bind Device to Platform Project​

Before registering the device, select the platform project it belongs to. Click the Project Dropdown to select an existing project. If no project has been created yet, create one first. For more details, refer to 【Create Project】.

lora_add_device_binding_project

Batch Excel​

Steps: Download template -> Fill in Excel -> Upload Excel -> If errors occur, edit online -> Click Next to complete device registration.

Download Template​

On the device registration page, click the red box to download the template file.

lora_add_device_download_temp

Fill in Excel​

Fill in the device information in the Excel. The MQTT template has two types: IoT devices and non-IoT devices.

IoT Device Template​

lora_add_device_download_temp_csv

  • DevEUI: Unique identifier for IoT devices, usually the DevEUI on the device. Required.
  • Device Name: Must be unique. Required.
  • Building Name: Location information. Required.
  • Location: Device location. Optional.
Non-IoT Device Template​

noniot_excel

  • rawId: Unique identifier for IoT devices, typically the ID for the device's function points. Required.
  • Building Name: Location information. Required.
  • Device Name: Device name. Multiple function points can share the same device name, and the system will treat these function points as part of the same device. Required.
  • Function Type: Device function points, must match the function points in the selected model. Required.
  • Location: Device location. Optional.
  • isIoT: Indicates whether it is an IoT device. If left empty, it defaults to non-IoT device. Optional.
Upload Excel​

Click/Drag the red box to upload the filled Excel file. The uploaded device information will be displayed in the online table. If there are errors, you can continue to add or modify.

mqtt_add_device_upload_temp

Online Editing​

Fill in device information directly on the page. Click the Add New button to add a new row and continue entering device information.

mqtt_add_device_ui_add_iot

After entering the device information, click Submit. A confirmation window will appear. Once confirmed, the device will be registered.

Note: Once device registration is successful, the status will be Registered, but not yet connected to real-time data. The system will subscribe to the reported data based on the configured parameters, clean it, and store it. After the data is processed, the device status will change to Connected and be displayed in the device list.

mqtt_add_device_submit_confirm_iot

Once registration is complete, you will be redirected to the Device Registration Page (the recently registered device data is shown in the red box). When the platform subscribes to the correctly formatted reported data, the device will be successfully integrated.

lora_add_device_submit_success

After successful registration, you can view the device information and data in the device management interface. For more details, refer to 【Device Management】.