Agent API docs now on devwiki

If you’ve been on the forums a while, you’ve probably already tired of me saying “that’s fixed with agents!”. Well, they’re not quite here but we thought we’d open up the API docs to let you see what’s coming next month.

An agent is a squirrel VM that runs on our servers. In the same way that the squirrel VM on the imp is all about talking to hardware via hardware APIs, the squirrel VM on the server is all about talking to web services via HTTP APIs. The agent is instantiated when an imp appears, and carries on running even if the imp sleeps or goes offline for a while. As such, it can do things like collect readings from an imp and offer them to a phone app.

As such, you can finally talk to all those things that the HTTP blocks weren’t able to… like take data from an HTTP request, send it to your imp, collect return data, and then reply to the request with fresh data from the imp.

Some small examples:


…and so on. More will be posted soon, we’ve been having a lot of fun with these!

There’s more in the API to come, but this is the basic meat of it. Let us know what you think!

Thanks for the updated Agent API Docs Hugo!

I had a quick question about the differences between functionality of InputPorts/OutputPorts and Agents. There seems to be a lot of overlap - is there any reason to continue to use InputPorts and OutputPorts over inter-Agent communications? Will InputPorts/OutputPorts become deprecated? The features seem somewhat redundant at this point with Agents having a lot more functionality.

Input/Outputports are the way to work with devices connected in the planner. These will continue to work whilst the planner exists, and are likely to be automatically transitioned to what comes next for developers.

…but, for commercial devices, there is no planner and hence you’d be using imp+agent.

looks awesome :slight_smile:
some things that pop to mind after reading i think all the docs:
*) is there a way for an agent to know its imp went offline, apart from sending pings every once in a while
*) can an agent get its own specific (base) url? so it can announce its in existence now somewhere
*) is there a delivery confirmation on imp<->agent message? or would a ‘ack’ send back be the way?
*) do features like persistent storage work in agents? to maintain data over server reboot or agent software update.

im sure i’ll come up with some more after my mind had some time to think about all the new posibilitys agents will bring!


Really we could do with another page, maybe worked-up from the stuff that the beta people got, that’s more like an overview of the whole agent set-up.

Remco: you’ll be pleased to know that all of those features are already being worked on (except the third, which, as you say, agent code can do itself with “ack”-type messages).


Not sure if it is in the plans, but I think one for would be pretty handy too.

the best would be an agent that you decide the format of the request’s data, you parse it yourself and pass it already encoded. that will give a large support for such services

Must say this really looks great. Can’t wait to get started with Agents!

MikeyDK: The example in http:urlencode shows how to do it. Just replace the URL to Pushovers URL and supply the proper parameters in s.

I know it can be done ejeklint, but I was looking for easier ways to do it.

Just hooked myself up to Pushover, can be very useful. This code snippet works fine but note it’s just an example:

function reportsuccess(res) { if (res.statuscode > 202) { server.log("Error: " + res.statuscode + " body: " + res.body); } } local podata = { "token": "xyz123Heimlich", "user": "AlsoHeimlich!", "message": "Bingbong!" }"", { "Content-Type": "application/x-www-form-urlencoded" }, http.urlencode(podata)).sendasync(reportsuccess);

Any update on when the release to us general user will happen.???

Well I ask my question again now that it is almost the end of March. When is the next release?

We’re still tracking down some issues and improving the UI before we open agents to everyone; we want to ensure that it’s a good experience. You’ll be glad to know we’ve been adding APIs and strengthening weak areas as we go (thanks to the beta group!)

If you need access now, you can email and request this - just bear in mind that it’s still in beta!

Thanks for the update.

“If you need access now, you can email and request this - just bear in mind that it’s still in beta!”

I do! E-mail who?

I tried to push message to my pushover account, sadly it didnt work.
I get the error: bad parameters to request.sendasync(callback)

What I did was sort of copy-paste into my agent code, as follows:
device.on("setMsg",function(value){ local podata = { "token": "MY-TOKEN-ID", "user": "mi2", "message": value };"", { "Content-Type": "application/x-www-form-urlencoded" }, http.urlencode(podata)).sendasync(); });

Any reasons why?

The HTTPRequest.sendasync() method always takes a callback function; without it, you’d have no way of knowing when the connection completed, or if it gave an error. Did you want sendsync() instead?


cant it take void parameter?
I tried changing to sync, but it didnt work as well