Carriots Provisioning Protocol: Previous Considerations
- Introduction to the Carriots Platform
- Getting a Carriots Account
- Developing Your Firmware (recommended)
- Developing Your Listeners (recommended)
- Provisioning Best Practices
Our platform is a M2M platform with 3 main goals:
- Fast and cheap M2M application development
- Easy IoT integration in your products
Carriots is device-centric: Carriots connects devices to devices, devices to other systems, systems to devices and systems to other systems. Everything connected to Carriots can be modelled as a device. Definitely, devices are everywhere in Carriots:
- Projects, Services, Groups and Assets are entities in a hierarchy for grouping and structure your devices.
- Streams are associated to devices.
- Listeners and Rules are related to events raised during a device lifetime.
- Carriots Hierarchy
For more information about Carriots please got to Carriots Ecosystem
First of all, to start working with Carriots you must obtain a Carriots account. Check the different possibilities you have HERE.
Once you have your account created, login into Carriots. Now, in the upper menu, click on My Settings --> My Account.
Besides your personal data, in your account information you can see three long strings:
- Full Privileges Apikey
- Automatic Apikey Read Only
- Automatic Apikey Stream Only
An apikey is an alternative to user credentials (user/password) for authenticating and authorizing a request to our platform.
We have provided three different apikeys with different privileges to fit your needs:
- Automatic Apikey Read Only: This apikey will let your devices ask Carriots for information via the Carriots API.
- Automatic Apikey Stream Only: This apikey will let your devices publishing data or status streams into Carriots as well as subscribing to a messaging queue, which works with MQTT protocol, managed by Carriots. By using the Carriots Control Panel, you can set a listener which deals with the streams. By publishing data and status streams, the world can see your device. By subscribing to a messaging queue, your device can see the world.
- Full Privileges Apikey: This apikey will let you do all operations possible, so it is better to use it only when necessary. For example, you can use this apikey inside a listener for CRUD operations over the Carriots entities you are managing. This would be the exact case for provisioning devices.
The firmware is the software you set in your device to get it working. This firmware must include the capability of communicating with Carriots to send/receive information.
To receive information from Carriots the firmware must implement a MQTT subscriber, which is a MQTT client capable of subscribing to topics.
To send information to Carriots, there are two ways:
- MQTT - publish: Only data streams can be sent this way.
- HTTPS - post: Data and Status streams can be sent this way.
A listener is a piece of code that allows you to process the streams sent by a device (remember a device can be an electronic device or a computing system).
These scripts run in the Carriots Platform and can be used for:
- Processing the Data Streams sent by your devices via asynchronous requests.
- Processing the Status Streams sent by your devices via synchronous requests.
Every device name must be unique. Our recommendation is using a device's attribute that makes it unique. This device attribute must be accessible from your firmware, so that your firmware can obtain it dynamically. Examples:
- The device M.A.C. address (this can be obtained from the WIFI or the ethernet chip).
- The device serial number. This implies the device manufacturer must include this serial number in a file inside the firmware, so that the firmware can read it.
- Any other mechanism that lets your firmware read a unique attribute dynamically.
Avoid using your Full Privileges Apikey inside your firmware. Use your Automatic Apikey Stream Only instead.