ImpCentral API Build & Dploy to devices

IDE & Tools
1

Do you have one complete example on how one can

  1. Use the ImpCentral API to complete the build and deploy to devices of the agent.nut and device.nut files?
  2. Use the ImpCentral API to get the logs of devices.

I have looked at the documentation for the API, which shows each of the API’s but does not list the steps one needs to take to achieve the above tasks.
It would be great if you can show a small example on how these tasks can be achieved using the API.

Thanks in advance.

2

It’s not clear to me from your question whether you’re comfortable with the concepts of products and groups that are exposed by the API. I’m going to assume less knowledge, rather than more.

The ImpCentral API exposes Products and DeviceGroups. Products are collections of DeviceGroups, and DeviceGroups are collections of Devices. DeviceGroups come in different flavors, depending on whether you’re dealing with development, factory, or production code.

A Deployment – the device code and agent code that you might think of as a “release” – is created on a DeviceGroup.

Given all that…

Deploying Code
From a high level, the steps are (there are many, but note that most only ever need to be done once):

  1. authenticate, receive an access token and refresh token; all the following steps require a valid access token
  2. create a Product (POST /v5/products)
  3. create a DeviceGroup (POST /v5/devicegroups)
  4. assign a device to the the DeviceGroup (POST /v5/devicegroups/:devicegroup_id/relationships/devices)
  5. create a Deployment (POST /v5/deployments)

… note that steps 4 and 5 can happen in any order; devices already in a group will run newly deployed code, devices added to a group will run the most recently deployed code for that group.

Getting Logs
Getting logs is a process of creating a log stream, and attaching logs for a device to that stream:

  1. create a logstream (POST /v5/logstream); note that you can only ever have one active logstream per account. This call will return a URL; while that URL may be in the /v5 hierarchy, please don’t depend on that – we reserve the ability to have these URLs be completely separate from our normal API hierarchy.
  2. start listening on the stream (GET <logstream URL>)
  3. add a device to the stream (PUT /v5/logstream/:logstream_id/:device_id)

… that’s it. You can add up to five devices to a logstream; newly added devices replace the least recently added device.

… does that answer your questions? If not, we can probably pull together a complete curl-and-response session log to make things even more explicit.

3

Thank you very much for a quick reply. How do the existing model’s and the devices in those models relate to the steps above?
Are the models the same as devicegroups?

4

Existing models aren’t a one-to-one with device groups, but that’s a reasonable way to think of them. While a development model is effectively equivalent to a development devicegroup, a production model is effectively two devicegroups – one development, one production.

Hope that made sense.

5

If the current models we have are NOT a one to one with the devicegroups, The current IMP ide does not have this construct, will this construct be added to the IDE?

6

The ImpCentral model requires a migration step to move from old world to new.

At the moment, our plan is to:

  1. provide a preview of the API (done, barring some upcoming additions)
  2. provide a preview of the new UI (coming)
  3. provide migration tools for customers (this means “everyone”, not just paying customers) to migrate models to the new world. Migrating models allows migration of code / factory setup, and optionally devices (coming)
  4. provide a deadline for migrations; after this point all current-world models will be auto-migrated to ImpCentral

… in short, you cannot depend on the new UI working with current-world models, or vice-versa; migration is a necessary intermediate step, and (for devices) it’s intended to be a one-way trip. The expectation is that customers will migrate code, verify that the structure makes sense, then migrate a few devices, and verify that UI expectations are being met, then finally to migrate all their devices.

7

Can i get a link to the new UI?

Thanks

8

Following up via DM.

9

Hi all, I just wanted to follow up with a little gotcha :wink:

By design ImpCentral API will not automatically run code from a newly created deployment on an already assigned device and its agent. Thus we have a missing step #6 in the “Deploying Code” section above. You have two options for running current (most recent) deployment on an already assigned device:

A) Restart the previously assigned device using POST /v5/devices/:device_id/restart
B) Restart all devices on the group using POST /v5/devicegroups/:group_id/restart

And as ahoughton mentioned, all newly assigned devices to a group will automatically run the current (most recent) deployment. So technically you could also re-assign a device to the same group again, but that’s just silly, simply restart as desired for your particular use case :slight_smile:

10

Hi,
I am trying to add a device into imp central Application Workspace. Couple of questions. Can the device exist in both the old model environment and in imp central workspace? I tried added my device that is already in the old build env to the new imp central workspace even though the device got added it says it is offline in the status.

Thanks
Rama.

11

Hi, Rama. Unassigned devices will show up in both the current IDE and in the impCentral UI. Other than that, devices won’t (or, at least, shouldn’t) appear in both worlds.

In re a device showing offline when you expect it online – if you’d like to private message me a device ID I’d be happy to look at our records, but I’d urge you to verify that the device is actually online (by periodically logging, for example) before assuming that the UI is incorrect.

12

Where the introduction of a new device (appearing as unassigned) happened almost instantly in the ‘old’ IDE before, it now takes up to 10mins for them to appear, and then not even simultaneously in both ‘worlds’. This is really not working well yet and I lost hours today figuring out what was wrong…
I would recommend not changing a working environment (old IDE) until you have the new one working properly.
Thank you…

13

Interesting. Can you send me the device id in question via DM, and – ideally – some description of what you were doing when the problem appeared? Both interfaces use the same underlying data and event source to display these changes – and have been for months – so it’s not clear why you’d see slow updates in the impCentral IDE.

14

Thanks for excellent support. Sorry it took me a while to get the flow of things and understand the object model mapping to finally be able to deploy. I am using Node JS to build the script to make these deployments happen, at first tried to find a library to use curl in NodeJS. Gave up that path and finally stuck to standard Nodejs requests to get it working.

Even though the entire object model API is all documented along with the JSON needed, it was not very clear to make the flow connection easily. A colleague of mine put the previous build system so for me your build process was completely new. It would greatly help if there is a single full example in javascript or curl with the full flow as below to deploy the agent and device code. I do understand you can do a lot more, in our case currently all devices are development_group type of devices.

following steps in one location (without going to individual sections of the api) in curl or javascript.

Get your access token…
use the access token obtained to find the device group…
Use the device group id to install the agent and device code content by making a deployment.
If you had this scenario example already, i just could not find it in the docs. Thanks.

Thanks for all your help.

Rama

15

Following your suggestion, I’ve added a page of sample code here.

16

Really appreciate your addition to the code example. I think it is very beneficial for anybody who is just starting out to make impCentral builds.

Thanks

17

I’ve just added a further example: device logging