MOKO SMART LoRaWAN device and ThingsBoard

This guide describes how to register a MOKO SMART LoRaWAN gateway and end devices in ThingsBoard using The Things Stack Community Edition (TTN) as the network server and a ThingsBoard MQTT integration to forward device data.

The guide applies to all MOKO SMART LoRaWAN end devices.

1. Power on the gateway and connect to its Wi-Fi access point. Open the Web GUI and note the gateway ID on the FUNCTION - Server Access page.

   

2. Log in to your TTN account and select the cluster for your frequency plan. For US915, select North America 1.

   

3. Go to the gateway console on the home page.

   

4. Click Register new gateway.

   

   Enter the gateway ID from step 1.

   

   Enter a TTN gateway ID, select United States 902-928 MHz as the frequency plan, and click Register gateway.

   

5. Get the gateway server address from the TTN General settings page.

   

   Enter the server address in the MKGW2 Web GUI with port 1700. Set the frequency to 915 and the channel to US915_CH08-15 to match the TTN configuration.

   

6. Verify the gateway connection. A green indicator in the Web GUI means the gateway connected successfully.

   

   Confirm the status on TTN as well.

   

1. In the TTN console, click Create an application.

   

2. Fill in the required application fields and click Create application.

   

3. Go to Integrations > MQTT in the left menu, then click Generate new API key.

   

4. Copy and save the generated API key. It will not be shown again after leaving the page.

   

1. Go to Integrations center > Integrations and click + to add a new integration. Select The Things Stack Community as the type and click Next.

   

2. Paste the following decoder into the Uplink data converter field and click Next.

   var data = decodeToJson(payload);
   
   var deviceName = data.end_device_ids.device_id;
   var deviceType = data.end_device_ids.application_ids.application_id;
   
   // If you want to parse incoming data somehow, you can add your code to this function.
   // input: bytes
   // expected output:
   //  {
   //    "attributes": {"attributeKey": "attributeValue"},
   //    "telemetry": {"telemetryKey": "telemetryValue"}
   //  }
   // default functionality - convert bytes to HEX string with telemetry key "HEX_bytes"
   
   function decodeFrmPayload(input) {
       var output = { attributes:{}, telemetry: {} };
       // --- Decoding code --- //
   
       output.telemetry.HEX_bytes = bytesToHex(input);
   
       // --- Decoding code --- //
       return output;
   }
   
   // --- attributes and telemetry objects ---
   var telemetry = {};
   var attributes = {};
   // --- attributes and telemetry objects ---
   
   // --- Timestamp parsing
   var incomingDateString = data.uplink_message.received_at;
   var dateString = incomingDateString.substring(0, incomingDateString.lastIndexOf(".")+3) + "Z";
   var timestamp = new Date(dateString).getTime();
   // --- Timestamp parsing
   
   // You can add some keys manually to attributes or telemetry
   attributes.f_port = data.uplink_message.f_port;
   attributes.settings = data.uplink_message.settings;
   // We want to save correlation ids as single object, so we are excluding them from attributes parse and add manually
   attributes.correlation_ids = data.correlation_ids;
   
   // You can exclude some keys from the result
   var excludeFromAttributesList = ["device_id", "application_id", "uplink_message", "correlation_ids"];
   var excludeFromTelemetryList = ["uplink_token", "gateway_id", "settings"];
   
   // Message parsing
   // To avoid paths in the decoded objects we passing false value to function as "pathInKey" argument.
   // Warning: pathInKey can cause already found fields to be overwritten with the last value found, e.g. receive_at from uplink_message will be written receive_at in the root.
   var telemetryData = toFlatMap(data.uplink_message, excludeFromTelemetryList, false);
   var attributesData = toFlatMap(data, excludeFromAttributesList, false);
   
   // Passing incoming bytes to decodeFrmPayload function, to get custom decoding
   var customDecoding = {};
   if (data.uplink_message.get("frm_payload") != null) {
       customDecoding = decodeFrmPayload(base64ToBytes(data.uplink_message.frm_payload));
   }
   
   // Collecting data to result
   if (customDecoding.?telemetry.size() > 0) {
       telemetry.putAll(customDecoding.telemetry);
   }
   
   if (customDecoding.?attributes.size() > 0) {
       attributes.putAll(customDecoding.attributes);
   }
   
   telemetry.putAll(telemetryData);
   attributes.putAll(attributesData);
   
   var result = {
       deviceName: deviceName,
       deviceType: deviceType,
       telemetry: {
           ts: timestamp,
           values: telemetry
       },
       attributes: attributes
   };
   
   return result;

   

3. Leave the Downlink data converter field empty and click Skip.

   

4. Fill in the connection fields with your TTN MQTT credentials and click Add.

   

1. In the TTN application console, go to End devices and click Register end device.

   

2. Select Enter end device specifics manually, choose the frequency plan matching your gateway, and select LoRaWAN version v1.0.3.

   

3. Enter the JoinEUI. The default MOKO SMART JoinEUI is 70 B3 D5 7E D0 02 6B 87.

4. Enter the DevEUI and AppKey. The DevEUI is printed on the package label. The default AppKey is 2B 7E 15 16 28 AE D2 A6 AB F7 15 88 09 CF 4F 3C. You can also read both values from the device using the MKLora app.

   

5. Click Register end device.

6. Verify the device status on TTN.

   

   Check Live data to confirm the device is uploading payloads.

   

7. Go to Payload formatters, paste the decoder from the MOKO SMART LoRaWAN decoder repository, and click Save changes.

   

8. In ThingsBoard, go to Entities > Devices. Devices registered in TTN appear automatically via the integration. Open a device and go to Latest telemetry to confirm data is arriving.

   

1. Go to Dashboards in the main menu, click + in the upper right corner, and select Create new dashboard. Enter a title and click Add.

   

1. Click + Add widget or the Add new widget icon in the center of the dashboard.

   

2. Find the Status indicators widget bundle and click on it.

   

3. Select the Battery level widget.

   

4. In the Add widget dialog, select your device as the datasource and set batt_level as the data key, then click Add.

   

   The battery level widget appears on the dashboard.

   

1. Click + Add widget to add another widget.

   

2. Find the Maps widget bundle and click on it.

   

3. Select the Google map widget.

   

4. In the Add widget dialog, select Device as the datasource type, choose your device, and add latitude and longitude as time series data keys. Click Add.

   

5. Click Save in the upper right corner to save the dashboard.

   

   The map widget displays the device’s location.