Skip to end of metadata
Go to start of metadata

Scenario: 

  1. A "Thermometer" device has just been purchased by its new owner
  2. The owner must register and activate his new device on GadgetKeeper using the serial number found on the device
  3. Upon activation, a "ThermometerDevice" thing is created on GadgetKeeper based on the serial number, if it doesn't already exist
  4. All activation calls generate a new API key, and drop the old API key if one exists from a previous activation call
  5. The device owner needs to check if the firmware version installed on the device matches the the latest working version
  6. If the versions don't match, the "target" version on the server-side must be downloaded and installed on the device
  7. Registration is finalized when the device confirms its installed firmware version on GadgetKeeper

Prerequisites: 

  1. "Thermometer" product created and device's serial number registered in the Create Product and Serial Number scenario
  2. A "ThermometerDevice" thing may have already been created in the Create Thing From Serial Number scenario
  3. A "target" version with firmware must have been created as explained in CreateTemplate Version

Steps: 

For more details, check the Device Provisioning interaction diagram.

1. Look up serial number

  1. Every new "Thermometer" device has a unique serial number to identify it
  2. The serial number must be looked up on the device. It should be something like: "THERM00000000000001"
  3. The method used for looking up a serial number depends on the particular device

2. Initiate activation

  1. Device calls the Activate method in Provision API using the given serial number:

  2. Device receives a response with API key and thing Id:

The device saves "apiKey" and "thingId" in non-volatile memory for future API calls. "apiKey" is the API Key which allows administrative access, and it can be used as authentication to both REST and Messaging calls.

The device has now been activated and registered on GadgetKeeper. If a "Thermometer" thing based on the given serial number does not exist, then it is created, and a dedicated admin API key is generated for its access. If a thing already exists for the serial number, it is not changed, but the old API key is dropped and a new one is generated

Whenever a thing is created using this API method, a name for it is generated with a number attached, such as "Thermometer 2". In order to change this name to "ThermometerDevice", the  Update thing method in Things API must be called with the given thing Id:

The device should then receive the response:

3. Get expected version information

  1. After activation, the owner should download and install the "target" version from GadgetKeeper if this version is not already installed on the device
  2. The target version is the latest firmware version that is usable for products in the field

  3. Device calls Get thing target version method in Provision API with the thing Id saved in step 2:

  4. Device receives a response with target version Id, name, and description:

If a firmware version hasn't been installed on the device, proceed directly to step 4 (Download and install firmware)

If the new device already has a firmware version installed, its Id information should be obtained and checked to see if it matches the Id sent back for the target version

3. Get version information for installed firmware

  1. If the Id for the installed version has already been stored in non-volatile memory, skip steps 3.2 and 3.3, and go to step 3.4 to compare the version Ids

  2. Device calls the Get thing current version method in Provision API with the thing Id saved in step 2:

  3. Device receives a response with current version Id, name, and description:

  4. Check if the current version Id matches the target version Id

If the version Ids match, then step 4 can be skipped. Otherwise, the version 2("d5673e80218f11e3a1c46c626dd90e00") firmware should be downloaded and installed on the device

4. Download and install firmware

  1. This procedure is followed only if the local version is out of sync with target version on the server

  2. Device calls Get version firmware method in Provision API with the thing Id and the version Id returned in step 3:

  3. Device receives a response with the firmware code:

  4. Device decodes response string and updates its firmware

The last step finalizes the registration process as the firmware version installed on the device is confirmed on GadgetKeeper

5. Confirm firmware update

  1. Device calls Update/switch thing to a new version method in Provision API with the Id information:

  2. Device receives the following response:

The device will automatically store the Id information for the installed firmware version in its internal non-volatile memory for future API calls.

The "Thermometer" device has now been completely registered and activated on GadgetKeeper, and is ready to use.

All of the API methods discussed here are explained in more detail on the Provision API page.

 

 

  • No labels