Skip to content

Commit f25addf

Browse files
matteosuppomatteosuppo
committed
Add a bit of docs on how to use the agent
1 parent 3dcbb73 commit f25addf

File tree

1 file changed

+218
-2
lines changed

1 file changed

+218
-2
lines changed

‎README.md

Lines changed: 218 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,224 @@ Please use the current latest version:
1919
* [MacOSX dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-osx-installer.dmg)
2020
* [Linux x64 dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-linux-x64-installer.run)
2121

22-
## Compiling
22+
## How to use it
23+
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.
24+
25+
It will listen to http and websocket connections on a range of ports from `8990` to `9000`.
26+
27+
### Discover the port
28+
You should make GET request to the `/info` endpoint on the possible ports, until you find a reply:
29+
30+
$ curl http://localhost:8990/info
31+
curl: (7) Failed to connect to localhost port 8990: Connection refused
32+
$ curl http://localhost:8991/info
33+

34+
$ curl http://localhost:8992/info
35+
{"http":"http://localhost:8992","https":"https://localhost:8991","version":"1.0.36","ws":"ws://localhost:8992","wss":"wss://localhost:8991"}
36+
37+
The reply will contain a json with info about the version and the http and https endpoints to use
38+
39+
### Open a websocket
40+
Most of the commands can be performed with websocket instructions. We use a library called [socket.io](https://cdnjs.cloudflare.com/ajax/libs/socket.io/1.3.5/socket.io.min.js) to handle the messages.
41+
Once you have the websocket endpoint you need you can:
42+
43+
```javascript
44+
var socket = io(endpoint);
45+
socket.on('connect', function () {
46+
socket.emit('message', yourCommand);
47+
48+
socket.on('message', function () {
49+
// Your code to handle messages
50+
})
51+
}
52+
```
53+
54+
### Use the debug console
55+
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:
56+
57+
log on
58+
59+
### List the boards
60+
To get a json list of the connected boards you can issue the command list:
61+
62+
```javascript
63+
socket.emit('command', 'list');
64+
```
65+
66+
You will receive an object of all the boards connected with USB or over the network:
67+
68+
```json
69+
{
70+
"Ports":[
71+
{
72+
"Name":"/dev/ttyACM0",
73+
"SerialNumber":"",
74+
"DeviceClass":"",
75+
"IsOpen":false,
76+
"IsPrimary":false,
77+
"Baud":0,
78+
"BufferAlgorithm":"",
79+
"Ver":"1.0.36",
80+
"NetworkPort":false,
81+
"VendorID":"0x2341",
82+
"ProductID":"0x8036"
83+
}
84+
],
85+
"Network":false
86+
}{
87+
"Ports":[
88+
{
89+
"Name":"192.168.1.101",
90+
"SerialNumber":"",
91+
"DeviceClass":"",
92+
"IsOpen":false,
93+
"IsPrimary":false,
94+
"Baud":0,
95+
"BufferAlgorithm":"",
96+
"Ver":"1.0.36",
97+
"NetworkPort":true,
98+
"VendorID":"board=Arduino Y\\195\\186n Shield distro_version=0.1",
99+
"ProductID":"Shield"
100+
}
101+
],
102+
"Network":true
103+
}
104+
```
105+
106+
## Open/Close ports
107+
108+
To read input from a board connected to USB you must first open the port with the command
109+
110+
open /dev/ttyACM0 9600
111+
112+
where you should replace /dev/ttyACM0 with the actual port and 9600 with the baud.
113+
114+
You will receive a message like:
115+
116+
```json
117+
{
118+
"Cmd":"Open",
119+
"Desc":"Got register/open on port.",
120+
"Port":"/dev/ttyACM0",
121+
"IsPrimary":true,
122+
"Baud":9600,
123+
"BufferType":""
124+
}
125+
```
126+
127+
or
128+
129+
```json
130+
{
131+
"Cmd":"OpenFail",
132+
"Desc":"Error opening port. Serial port busy",
133+
"Port":"/dev/ttyACM0",
134+
"Baud":9600
135+
}
136+
```
137+
138+
You can then close the port with
139+
140+
close /dev/ttyACM0
141+
142+
You will receive a message like:
143+
144+
```json
145+
{
146+
"Cmd":"Close",
147+
"Desc":"Got unregister/close on port.",
148+
"Port":"/dev/ttyACM0",
149+
"Baud":9600
150+
}
151+
```
152+
153+
or
154+
155+
156+
```json
157+
{
158+
"Error":"We could not find the serial port /dev/ttyACM0 that you were trying to close."
159+
}
160+
```
161+
162+
### Receiving and sending data
163+
164+
While a port is open you can send input with
165+
166+
send /dev/ttyACM0 hello
167+
168+
with a reply like
169+
170+
```
171+
{"Cmd":"Queued","QCnt":1,"Ids":[""],"D":["hello"],"Port":"/dev/ttyACM0"}
172+
{"Cmd":"Write","QCnt":0,"Id":"","P":"/dev/ttyACM0"}
173+
{"Cmd":"CompleteFake","Id":"","P":"/dev/ttyACM0"}
174+
175+
You can receive output from the serial port by listening to messages like this:
176+
177+
```json
178+
{
179+
"D":"output string\r\n"
180+
}
181+
```
182+
183+
### Download a tool
184+
You can download a tool on the computer with a command like
185+
186+
download avrdude
187+
188+
receiving a reply like
189+
190+
```json
191+
{
192+
"DownloadStatus": "Success",
193+
"Msg":"Map Updated"
194+
}
195+
```
196+
197+
### Upload
198+
You can upload a binary sketch to a board connected to a port with a POST request to be made at the http endpoint.
199+
200+
The payload is a json object that looks like this:
201+
202+
```json
203+
{
204+
"board":"arduino:avr:leonardo",
205+
"port":"/dev/ttyACM1",
206+
"commandline":"\"{runtime.tools.avrdude.path}/bin/avrdude\" \"-C{runtime.tools.avrdude.path}/etc/avrdude.conf\" {upload.verbose} -patmega32u4 -cavr109 -P{serial.port} -b57600 -D \"-Uflash:w:{build.path}/{build.project_name}.hex:i\"",
207+
"signature":"97db97ced2c",
208+
"hex":"OjEwMDAwMDAwMEM5NEU1MDAwQzk0MEQwMTBDOTQwRDAxMEM5NDBEMDE2MQ0KOjEwMDAxMDAwMEM5NDBEMDEwQzk0M",
209+
"filename":"Blink.ino.hex",
210+
"extra":{
211+
"auth":{
212+
"password":null
213+
},
214+
"wait_for_upload_port":true,
215+
"use_1200bps_touch":true,
216+
"network":false,
217+
"params_verbose":"-v",
218+
"params_quiet":"-q -q",
219+
"verbose":true
220+
}
221+
}
222+
```
223+
224+
- commandline is the command to execute to perform the upload. This is for example avrdude on a leonardo.
225+
226+
- hex contains the sketch hex encoded in base64
227+
228+
- 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
229+
230+
The results of the upload will be delivered via websocket with messages that looks like:
231+
232+
```json
233+
{"Msg":"avrdude: verifying ...","ProgrammerStatus":"Busy"}
234+
{"Msg":"avrdude done. Thank you.","ProgrammerStatus":"Busy"}
235+
{"Flash":"Ok","ProgrammerStatus":"Done"}
236+
237+
---
238+
239+
## Development
23240
24241
From the project root dir executing:
25242
```
@@ -96,4 +313,3 @@ By making a contribution to this project, I certify that:
96313
## Creating a release
97314
Just create a new release on github, and our drone server will build and upload
98315
ithe compiled binaries for every architecture in a zip file in the release itself.
99-

0 commit comments

Comments
 (0)