Skip to content

How to use the agent

Jump to bottom
Umberto Baldi edited this page May 25, 2023 · 8 revisions

The arduino create agent is a single binary that reads from a configuration file. Upon launching it will sit on the traybar and work in the background.

It will listen to http/https and websocket connections on a range of ports from 8990 to 9000.

Discover the port

You should make GET request to the /info endpoint on the possible ports, until you find a reply:

$ curl http://127.0.0.1:8990/info
curl: (7) Failed to connect to 127.0.0.1 port 8990: Connection refused
$ curl http://127.0.0.1:8991/info

$ curl http://127.0.0.1:8992/info
{"http":"http://127.0.0.1:8992","https":"https://127.0.0.1:8991","version":"1.0.36","ws":"ws://127.0.0.1:8992","wss":"wss://127.0.0.1:8991"}

The reply will contain a json with info about the version and the http and https endpoints to use

Open a websocket

Most of the commands can be performed with websocket instructions. We use a library called socket.io to handle the messages. Once you have the websocket endpoint you need you can:

var socket = io(endpoint);
socket.on('connect', function () {
    socket.emit('command', yourCommand);

    socket.on('command', function () {
        // Your code to handle messages
    })
}

Use the debug console

By clicking on the tray icon and going to the debug console you can try most of the websocket commands. The first command you should type in is:

log on

List the boards

To get a json list of the connected boards you can issue the command:

list

You will receive an object of all the boards connected with USB or over the network:

{
  "Ports":[
    {
      "Name":"/dev/ttyACM0",
      "SerialNumber":"",
      "DeviceClass":"",
      "IsOpen":false,
      "IsPrimary":false,
      "Baud":0,
      "BufferAlgorithm":"",
      "Ver":"1.0.36",
      "NetworkPort":false,
      "VendorID":"0x2341",
      "ProductID":"0x8036"
    }
  ],
  "Network":false
}{
  "Ports":[
    {
      "Name":"192.168.1.101",
      "SerialNumber":"",
      "DeviceClass":"",
      "IsOpen":false,
      "IsPrimary":false,
      "Baud":0,
      "BufferAlgorithm":"",
      "Ver":"1.0.36",
      "NetworkPort":true,
      "VendorID":"board=Arduino Y\\195\\186n Shield distro_version=0.1",
      "ProductID":"Shield"
    }
  ],
  "Network":true
}

Open/Close ports

To read input from a board connected to USB you must first open the port with the command

open /dev/ttyACM0 9600 [buffer type]

Where you should replace /dev/ttyACM0 with the actual port and 9600 with the baud.

You can specify a buffer type to use when opening a serial connection, you can use either:

  • timed: the one used with the web editor
  • default: it does not use a buffer. It's the one used if not specified.
  • timedraw: the serial communication happens in a binary format without UTF8 encoding. But the messages are encoded in base64, you have to decode them to read them.

You will receive a message like:

{
  "Cmd": "Open",
  "Desc": "Got register/open on port.",
  "Port": "/dev/ttyACM0",
  "Baud": 9600,
  "BufferType": "default"
}

or

{
  "Cmd":"OpenFail",
  "Desc":"Error opening port. Serial port busy",
  "Port":"/dev/ttyACM0",
  "Baud":9600
}

You can then close the port with

close /dev/ttyACM0

You will receive a message like:

{
  "Cmd":"Close",
  "Desc":"Got unregister/close on port.",
  "Port":"/dev/ttyACM0",
  "Baud":9600
}

or

{
  "Error":"We could not find the serial port /dev/ttyACM0 that you were trying to close."
}

Receiving and sending data

While a port is open, you can send input with

send /dev/ttyACM0 hello

with a reply like

send /dev/ttyACM0 hello

You can also send binary data with sendraw command, the same way you do with send. The data must be encoded in base64 format. The agent decodes it and sends the binary data back to the board. If you use timedraw as buffertype you get also the base64 encoding of the binary data from the board.

You can receive output from the serial port by listening to messages like this:

{
  "P": "/dev/ttyACM0",
  "D":"output string\r\n"
}

Download a tool

You can download a tool on the computer with a command like

downloadtool avrdude 6.0.1-arduino5 replace

receiving a reply like

{
  "DownloadStatus": "Success",
  "Msg":"Map Updated"
}

The syntax of the command is:

downloadtool {{name}} {{version}} {{behaviour}}

where version can be a version number of the string "latest", and behaviour can be "keep" (which skips the download if the tool already exists) and "replace" (which will download it again).

Upload

You can upload a binary sketch to a board connected to a port with a POST request to be made at the http endpoint.

The payload is a json object that looks like this:

{
   "board":"arduino:avr:leonardo",
   "commandline":"\"{runtime.tools.avrdude.path}/bin/avrdude\" \"-C{runtime.tools.avrdude.path}/etc/avrdude.conf\" -v -patmega32u4 -cavr109 -P{serial.port} -b57600 -D \"-Uflash:w:{build.path}/{build.project_name}.hex:i\"",
   "data":"OjEwMDAwMDAwMEM5NEU1MDAwQzk0MEQwMTBDOTQwRDAxMEM5NDBEMDE2MQ0KOjEwMDAxMDAwMEM5NDBEMDEwQzk0M",
   "extra":{
      "auth":{
         "username":null,
         "password":null,
         "private_key":null,
         "port":null
      },
      "use_1200bps_touch":true,
      "wait_for_upload_port":true
   },
   "extrafiles":[
      
   ],
   "filename":"Blink.hex",
   "hex":"OjEwMDAwMDAwMEM5NEU1MDAwQzk0MEQwMTBDOTQwRDAxMEM5NDBEMDE2MQ0KOjEwMDAxMDAwMEM5NDBEMDEwQzk0M",
   "network":false,
   "port":"/dev/ttyACM1",
   "signature":"97db97ced2c"
}

  • commandline is the command to execute to perform the upload. This is, for example, avrdude on a Leonardo.

  • hex contains the sketch binary encoded in base64 (could decode in Intel hex or raw binary)

  • signature is the signature of the commandline signed with the private key that matches the public key contained in the config.ini of the arduino-create-agent

The results of the upload will be delivered via websocket with messages that look like:

{"Msg":"avrdude: verifying ...","ProgrammerStatus":"Busy"}
{"Msg":"avrdude done. Thank you.","ProgrammerStatus":"Busy"}
{"Flash":"Ok","ProgrammerStatus":"Done"}

Javacript client library

You can install the arduino-create-agent-js-client in your client application

Clone this wiki locally