Thingsee Open Device API

There are ways to make any sensor connected and managed through the open API, so that the application & services creators can focus on creating their stuff instead of worrying about the hardware

Thingsee Open Device API is a low-level API and message description for IoT device vendors. This helps you to make Thingsee-compatible mesh sensors, trackers, gateways, and/or other actors or devices connected to the same Wirepas network or as a standalone devices. Thingsee Open Device API is visible for the application layer as Thingsee message JSON.

The specification is based on open cbor.io data format and is expandable practically to any use-case. This specification is free to use and expand, even when not used with Thingsee OPERATIONS CLOUD or Thingsee GATEWAYs; the only requirement is to have the governance through the official Thingsee message allocation process.

This specification can be used for NB-IoT sensors and others outside of Wirepas local communication. We are using this in our gateway and different GPS tracking products and the likes when there is a need to have bandwidth optimized messaging.

How to get started

Follow these simple steps if you want to start using this specification in your device. Contact support@haltian.com whenever you have more questions or would like to acquire your own address-space or a profile.

1. Request your own IMC (Internal Model Code)

Every connected device must have their own globally unique identifier. This is done by prepending vendor own serial number with a model code that creates an unique address-space for the products.

{your IMC} + {your serialnumber or Wirepas node id} is a globally unique identifier for your products.

See how Thingsee identifier (tuid) is constructed.

{
    "companyIdentifier" : "EX",
    "modelIdentifier"   : "FF",
    "hardwareRevision"  : "01"
}
  • companyIdentifier uses 2-character identifier to identify the company. For example “Example Inc” could be marked as “EX”. Numbers are allowed.
  • modelIdentifier uses 2-character identifier to identify product model. For example “FF” could be a “FootFall sensor”. numbers are allowed.
  • hardwareRevision uses 2-character idenfier to identify product/hardware revision. This could be just a running number “01” or letters; e.g. “SE” for Special Edition.

Thingsee Unique Identifier (tuid) is then constructed by combining your IMC value to your product serial numbers. This makes each sensor unique within the address space regardless of the manufacturer.

2. Request your own Thingsee Message Profile or start using the existing profiles that are publicly available.

  • For example, you can freely use Thingsee Environment Profile (12) and its tsmId 12100 to start sending temperature information. Likewise you should use Thingsee Common Profile (1) and its tsmId 1110 to send a battery information.
  • Feel free to contact us if you think that there should be additional fields for tsmId 12100 or a new message for environment profile. We can always add new properties and messages under existing profiles if that makes your life easier.
  • You should request a new dedicated profile if your product is such that there is no suitable profile yet - or if you want to have a private profile so that its specification is not published.

3. Create your firmware

  • During this process we will give you more detailed information about the Wirepas configuration parameters and help you to setup a test and verification environment using full Thingsee life-cycle management tools and services.

4. Get support to official Thingsee tools and services

  • Your product will be added to Thingsee ADMIN tools and Thingsee CLOUD so that it becomes part of the daily operations.
  • This is a significant benefit for your product as you just got a full device life-cycle management tools and services by doing almost nothing.

5. Publish to support.haltian.com - or keep private

  • Once the firmware is done and verified, your product can be published to support.haltian.com so that it becomes available for Haltian Sales and existing Thingsee customers.
  • This step requires that some generic information, and support and marketing material is created especially if your product becomes part of the official SLA-enabled offering.

Contact sales@haltian.com to get this process started. Our sales team propably already has a customer waiting for your product/use-case, so it is worth to check how to get your product offered to the growing Thingsee customer base.

Other integration options for IoT Devices

There are ways to make any existing hardware product Thingsee compatible; having any existing radio or not. If you happen to have nRF52-series radio, then it is just a new firmware and the job is done. Otherwise there needs to be more careful planning and hardware design. Contact sales@haltian.com and they will help you to find the best way to get your device connected.

It is also possible to make the compatibility at the cloud level; we can open and create conversion within Thingsee OPERATIONS CLOUD, so that your specific connectivity and data payload is converted to this open API in the cloud. As the specification is open, the conversion can be done anywhere without Thingsee cloud.

You can check some of our references about the custom connectivity products and projects we have done.