1NCE OS
How to integrate NB-IoT or Cellular Devices using the 1NCE OS plugin and SIM cards.
What is 1NCE OS?
1NCE OS simplifies NB-IoT, making it as user-friendly as LoRaWAN. Here's an explanation.
Numerous ready-to-use NB-IoT devices exist, predominantly utilizing low-power, compact payload size communication protocols such as UDP, CoAP, or LwM2M.
These devices typically allow configuration in their respective protocol (UDP, CoAP, MQTT, etc.) and payload format (Hex, JSON, Binary).
But then, what's next?
Device manufacturers usually focus on the device itself, offering choices for protocol, connectivity, and payload type. However, the question arises: where does the data go?
For tasks like displaying device data on dashboards, conducting analytics, or sending notifications, the integration process of these devices is often complex, prone to failure, and demands specialized skills.
It involves managing middleware, message communication protocols, and establishing translation services to feed data into preferred application platforms like Datacake.
The Limitations of SIM Cards
A SIM card labeled 'IoT' doesn't necessarily enhance the experience. Often, they only provide connectivity, leaving you to handle everything else.
This is especially challenging with NB-IoT, as direct data transmission to endpoints is frequently impossible without specific network settings.
1NCE OS: The Solution
1NCE OS addresses these challenges, offering a connectivity solution that includes a server for UDP, CoAP, and a message translation component. This component converts UDP or CoAP payloads, regardless of their format (Hex, Base64, Binary, JSON), into HTTPS calls.
Integration with Datacake
For Datacake users, the best part of the 1NCE OS is a dedicated Datacake plugin, which you can select on the 1NCE OS platform.
Here's how it functions:
Insert the 1NCE OS IoT Card into a sensor or custom device.
Set up your device to transmit data via UDP or CoAP to 1NCE OS servers.
Sign up for free on Datacake.
Activate the Datacake Plugin on 1NCE OS.
Copy your Workspace ID from Datacake and enter it into the Datacake Plugin on 1NCE OS.
Transmit data from your devices and watch them appear on Datacake.
Getting Started
Let’s delve into it, step by step.
Signing Up on Datacake
If you haven't already, register on the Datacake platform. It's free and doesn't require a credit card.
Adding Your First 1NCE Device
Once registered on Datacake, you'll be directed to your initial workspace, which will be empty. Your first task is to add a new device.
Simply click the "Add Device" button located in the top right corner, select "1NCE" from the list of available devices, and then click on next.
Workspace ID
On the subsequent screen, you might see a notification stating, “There are no 1NCE devices.”
On this same screen (modal), you'll find a text box labeled “Workspace ID” and a button to copy this ID to your clipboard.
Please proceed to copy this ID. This is the identification ID needed for the next step in the 1NCE OS Datacake Plugin.
Set Up Plugin
Now head back to the 1NCE OS configuration portal. In the configuration section of your 1NCE OS portal, you can choose from available plugins.
Select the Datacake plugin from this list.
Install Plugin
Upon clicking on the plugin, you'll be directed to an information page with an option to install the plugin. Please proceed with the installation.
Configure Plugin
After the plugin's installation in your 1NCE OS configuration, a setup page will appear. Here, the only detail required is the Workspace ID you copied earlier from Datacake when adding a new device.
Please paste the Workspace ID into the empty text field and confirm your setting by clicking on “Proceed.”
Add Plugin
Once the plugin installation is successful, you will receive a notification. You can now return to your Datacake Workspace.
How it Works
To understand the integration, it's important to know that the 1NCE OS Datacake plugin now recognizes a connected workspace using the provided Workspace ID.
This ID is included in the data forwarded from your devices on 1NCE OS.
When new data about an unknown device arrives at the Datacake backend, the platform identifies which workspace the devices belong to.
Send Data
To list your first device on Datacake, you need to send data from your devices. Please note: Only data sent AFTER the plugin installation will automatically list your devices in the Datacake Workspace.
Add Devices
After ensuring your devices have sent data, return to the Datacake platform, refresh the page, and click on "Add Device" again. Choose the 1NCE Device Type and click next.
Instead of the message “There are no 1NCE devices,” you should now see a list of devices that have sent data to the Datacake platform.
To add these devices, select the corresponding device or multiple devices, then click next to proceed.
Choosing a Product
The next step involves selecting a product type for your device(s).
What is a Product
All devices on Datacake are associated with a product. The product encompasses the device definition, payload decoder, dashboard design, database fields, configuration, and more.
Adding multiple devices to the same product means they all share the same dashboard layout, payload decoder, and database fields, but store data and trigger alerts individually. Changes to the product apply to all devices within that product.
NOTE: Selecting multiple devices for addition adds them all to the same product. If you are unsure of the implications, go ahead add devices one by one.
When to Use a Product
Using a common product is beneficial when deploying a large fleet of identical devices. Read more about products in the following guide.
Choosing a Template
For an easier start with 1NCE OS, product templates are available. Choose “New Product from template” and select from the provided templates, including the “1NCE OS Base Device Template.”
Select Plan
Next, select a plan. Datacake supports up to five free devices, along with various self-service plans. Choose a free plan to start.
Access Device
Once your devices are added, they'll appear in your workspace. Click on a device to access its dashboard, which initially shows only a map using location data from 1NCE OS.
Activate Location Service
To display your devices' locations on the map, activate the Location Feature in your 1NCE OS configuration.
Debug Communication
To verify incoming messages from your devices, navigate to the “Debug” Section in your device overview on Datacake.
Payload Decoder
1NCE OS transforms device data into a webhook. Datacake uses a Payload Decoder to interpret this data. You can access and modify the payload decoder in the “Configuration” settings of your 1NCE OS device on Datacake.
The Decoder
1NCE OS sends payloads in JSON or Base-64. The base decoder allows custom decoding code for payload extraction.
Testing the Decoder
You can test the decoder with provided examples. The output is displayed in various sections, like Output, Console.Log Output, and Recognized Measurements.
Working with JSON
The easiest way to get started without making any modifications is by forwarding JSON from 1NCE OS. This allows the base decoder to automatically decode the JSON values into lists that are compatible with Datacake. By using the "Try Decoder" function, you can view these decoded values on the "Recognized Measurements" Textbox.
If any of these listings have a red background, you can click on them to open a prefilled page on Datacake. This page will allow you to add those fields to your device's Database.
To test this feature, you can use the following payload:
{"type":"TELEMETRY_DATA","device":{"iccid":"YOUR ICCID"},"payload":{"type":"JSON","value":{"temperature":23.43,"battery":3.43}}}
Working with Binary, Hex, or Base64
If you are dealing with data that is not in JSON format, you must include a decoding mechanism in the base decoder.
The base decoder also includes a function that allows you to convert a string representation of hexadecimal into a buffer or byte array, which can be found in the base decoder. To decode the payload, you can use the base64Decode function, like this:
var decodedPayload = base64Decode(payload.value)
Once the payload is decoded, you can perform traditional byte decoding by using techniques such as bit shifting or bitwise AND operations to convert the bytes into floats, integers, or extract boolean values.
Suggested Fields
If your devices use JSON and have transmitted data, the base decoder might suggest new database fields based on incoming JSON fields.
You can go ahead and test this by providing the following example payload in the testing features on the decoder section.
Troubleshooting
If you encounter any difficulties while adding your devices, please contact us at support@datacake.de.
Last updated