Skip to content

How to use the agent

Jump to bottom
per1234 edited this page Aug 3, 2024 · 8 revisions

Arduino Cloud Agent is a single binary that reads from a configuration file. Upon launching, it will sit on the tray bar 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 all the possible ports, until you find the correct one (the agent answers back)

$ 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
{"http":"http://127.0.0.1:8991","https":"https://localhost:8992","origins":"https://local.arduino.cc:8000","os":"linux:amd64","update_url":"https://downloads.arduino.cc/","version":"0.0.0-dev","ws":"ws://127.0.0.1:8991","wss":"wss://localhost:8992"}

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 then "Open Debug Console" you can try most of the websocket commands. The first command you should type in is:

log on

This command will enable the output logging of the agent in the debug console

List the boards

To get a 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:

Network Ports:
[]

Serial Ports:
[
  {
    "Name": "/dev/ttyACM1",
    "SerialNumber": "510B3982514D503535202020FF103129",
    "IsOpen": false,
    "VendorID": "0x2341",
    "ProductID": "0x804e"
  }
]

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 baudrate.

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 buffer type, 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 (from the Arduino package-index.json) on the user's 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:

  • name identifies the tool we are going to download
  • version can be a version number or the string "latest"
  • behaviour can be "keep" (which skips the download if the tool already exists) or "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"
}

Where:

  • board is the fqbn of the board we are uploading to.
  • commandline is the command to execute to perform the upload. This is, for example, avrdude on a Leonardo.
  • filename is the name of the file contained by the next field
  • hex contains the sketch binary encoded in base64 (could decode in Intel hex or raw binary)
  • network allows performing the upload via network
  • port is the address to use for the upload
  • signature is the signature of the commandline signed with the private key that matches the public key contained in the config.ini of Arduino Cloud Agent

The output of the tool used for the upload will be delivered via websocket with a message that looks like this:

{"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