Testers wanted: ‘Build’ your own IDE

IDE & Tools
1

We’ve mentioned in the past that we’re working on an API to allow developers to link their own tools to the Electric Imp platform and so use those tools instead of the online IDE. I’m pleased to announce that the API, called Build, is now being opened to forum members for beta testing after a short closed beta test period.

Virtually any task that you can currently perform with the IDE, can be performed using the Electric Imp Build API. For example, Build provides a way to list the models you’ve created and any devices associated with them. Devices can be moved from model to model, their human-friendly names changed, or placed in an unassigned state. Device logs can be downloaded for inspection, and streamed to you as they are posted. New models can be created, old one deleted. Agent and device code can be uploaded, and older versions accessed. Devices can be restarted.

You might use Build to create your own desktop IDE using your computer’s native language and SDK, or a cross-platform tool like Java. Alternatively, you can use Build as the basis for a plug-in to be loaded by your favorite text editor. In each case, you can develop code offline and keep your source files locally, or on your own server. This in turn facilitates easier collaborative coding.

You can find full documentation for Build here: electricimp.com/docs/buildapi/.

To make use of Build, you will require an API key to authorize your calls. You can request your key by emailing beta@electricimp.com and providing your Electric Imp account name. You’ll then get a message from support@electricimp.com containing a link to onetimesecret.com – follow the link to retrieve your key.

If you’re testing Build alongside the IDE, you should note that changes made using Build will be reflected in the IDE, however it may be necessary to refresh the browser in which the IDE is being viewed if, for instance, it is showing a model that is also being modified via the API.

Build’s scope is currently restricted to actions performed using the IDE for software development.

The Electric Imp Build API is currently being made available in a pre-release form for testing and evaluation, and to gain feedback from trusted developers. As such, it should NOT be used with code that is business or project critical. You should also be aware that Build’s endpoints and properties may change before final release.

Please post any feedback you have – we want to hear your thoughts on the API’s details as well as an issues you are having – below.

And let us know what tools you end up using with Build.

2

It’s very minor, but the documentation for retrieving logs shows “device” in the Endpoint and Notes sections, but “devices” in the two examples.

3

Thanks, @hvacspei – will change.

4

Any chance of a PHP curl example? I’ve tried a couple times, even changing “devices” to “device”, but without success. I continue to get “unauthorized”. I’ve used curl a number of times in the past, but without the required header and that may be my stumbling point (assuming my APIKEY has been authorized by the Electric Imp).

Here’s a sanitized version of what I’m trying:
`

<?php $apikey = rawurlencode("000000000000000000000000"); $deviceid = "2000000000000000"; $timeout = 5; $url = "https://build.electricimp.com/v4/device/".$deviceid."/logs"; $ch = curl_init(); curl_setopt($ch,CURLOPT_URL,$url); curl_setopt($ch,CURLOPT_RETURNTRANSFER,1); curl_setopt($ch,CURLOPT_CONNECTTIMEOUT,$timeout); curl_setopt($ch,CURLOPT_HTTPHEADER,array ("Authorization: Basic ".$apikey)); $data = curl_exec($ch); curl_close($ch); var_dump($data); echo "
data: ".$data; ?>

`

I always get a “unauthorized” response:
{"success":false,"error":{"code":"Unauthorized","message_short":"Unauthorized","message_full":"Unauthorized"}}

5

@Tom, I have sent you an alternative key to try.

6

I’ve now also had a chance to try out the Build API, and here are some first thoughts.

  • It seems you need two round-trips to get the newest revision of a model (one call to get all the revisions, in order to determine the highest version number - and then another call to fetch that particular revision). As this appears to be a common thing to do, it would be handy with a single operation for doing this - for example:`/models/[id]/revisions/last`
  • It would also be useful to get information about what revision of a model is currently running on a device. When you query for a specific device, you can only get the model id, but not the version. Perhaps also some more device metrics like online-since, last-seen-online, etc.
And a few minor issues in the documentation.
  • For most of the operations the documentation still says that the response object contains a status object (and not just the Boolean success property as described on the main page - and found in the actual responses).
  • The short version of the code revision also contains the release_notes (here).
  • Uploading a new code revision returns an object with a revision property - not revisions (here).
Thanks for a solid API.
7

Splendid feedback, @qunuq - thanks very much indeed.

8

The new key worked for a while, but my calls always indicated the device could not be found. Now I seem to be getting the unauthorized response, likely due to too many failed calls.

I tried both with the curl log example in the docs and with my PHP code, but without success. I really hate to be a bother for what is most likely an error on my part.

I will try some other (non-log) calls to see if I have success with them.

–update–
I am able to list devices and models, so the API key appears to be valid.

The issue seems to be related to specifying the device ID to get the logs.

9

Just spotted that your URL in the example above is incorrect. The line should read:

$url = "https://build.electricimp.com/v4/devices/".$deviceid."/logs";

ie. ‘devices’ not ‘device’. I know you switched it to that deliberatly - did you switch back with the new key?

10

PS. An incorrect device ID will of course result in failure. If you’re getting a { “success” : false} back, you should look at the result’s error value

11

@smittytone, I had corrected the “devices” code but with no benefit. However, I believe I’ve stumbled across (part of) the problem. When I list devices, it lists 10 of them – far fewer than I have on my developer account. If I choose one of the listed devices, we’re golden. However, if I choose a device that’s not returned on the device listing, it indicates it can’t find the device. I hope there will not be limit to the number of devices/models/etc.

I did all the above testing with curl and haven’t yet tried the same with PHP.

12

OK…I was dense. I was using the wrong PHP function to base64 encode the APIKEY. It’s working now. I’ll post my code for others. Sorry for wasting your time.

13

For what it’s worth, here’s a simple PHP snippet that lists the logs for the device ID specified. BTW, it’s often humbling how the simplest bit of code can be so frustrating.

`

<?php $apikey = base64_encode("YOUR BUILD APIKEY"); $deviceid = "YOUR DEVICE ID"; $timeout = 5; $url = "https://build.electricimp.com/v4/devices/".$deviceid."/logs"; $ch = curl_init(); $rc = curl_setopt($ch,CURLOPT_URL,$url); $rc = curl_setopt($ch,CURLOPT_RETURNTRANSFER,1); $rc = curl_setopt($ch,CURLOPT_CONNECTTIMEOUT,$timeout); $headers = array ('Content-Type: application/json', 'Authorization: Basic ' . $apikey); $rc = curl_setopt($ch,CURLOPT_HTTPHEADER,$headers); $data = curl_exec($ch); $data_decoded = json_decode($data,true); //$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); //echo "status: ".$status; curl_close($ch); //var_dump($data_decoded); for ($i=0;$i<count($data_decoded["logs"]);$i++) { //if ($data_decoded["logs"][$i]["type"]=="agent.log") //uncomment to list only agent log entries { echo $data_decoded["logs"][$i]["timestamp"]." "; echo $data_decoded["logs"][$i]["type"]." "; echo $data_decoded["logs"][$i]["message"]."
"; } } ?>`
14

As more or less indicated in the docs, it seems like production devices won’t work.
Usefull functions for production devices should include :

  • device info (connection state & rssi value)
  • device/agent logs (200 entry history and streaming)
  • perform device & agent restart
  • last connection timestamp (does not exist yet in the beta as far as I could see)

these would be already highly desirable as it would allows us to build a proper support tool.
Manipulation of code and models for production is not needed.