Skip to content

Commit 035dfe4

Browse files
facchinmfacchinm
committed
Merge pull request arduino#104 from arduino/docs
Add a bit of docs on how to use the agent
2 parents 3dcbb73 + 319e0f5 commit 035dfe4

File tree

1 file changed

+220
-2
lines changed

1 file changed

+220
-2
lines changed

‎README.md

Lines changed: 220 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,226 @@ 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+
```json
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+
176+
You can receive output from the serial port by listening to messages like this:
177+
178+
```json
179+
{
180+
"D":"output string\r\n"
181+
}
182+
```
183+
184+
### Download a tool
185+
You can download a tool on the computer with a command like
186+
187+
download avrdude
188+
189+
receiving a reply like
190+
191+
```json
192+
{
193+
"DownloadStatus": "Success",
194+
"Msg":"Map Updated"
195+
}
196+
```
197+
198+
### Upload
199+
You can upload a binary sketch to a board connected to a port with a POST request to be made at the http endpoint.
200+
201+
The payload is a json object that looks like this:
202+
203+
```json
204+
{
205+
"board":"arduino:avr:leonardo",
206+
"port":"/dev/ttyACM1",
207+
"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\"",
208+
"signature":"97db97ced2c",
209+
"hex":"OjEwMDAwMDAwMEM5NEU1MDAwQzk0MEQwMTBDOTQwRDAxMEM5NDBEMDE2MQ0KOjEwMDAxMDAwMEM5NDBEMDEwQzk0M",
210+
"filename":"Blink.ino.hex",
211+
"extra":{
212+
"auth":{
213+
"password":null
214+
},
215+
"wait_for_upload_port":true,
216+
"use_1200bps_touch":true,
217+
"network":false,
218+
"params_verbose":"-v",
219+
"params_quiet":"-q -q",
220+
"verbose":true
221+
}
222+
}
223+
```
224+
225+
- commandline is the command to execute to perform the upload. This is for example avrdude on a leonardo.
226+
227+
- hex contains the sketch hex encoded in base64
228+
229+
- 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
230+
231+
The results of the upload will be delivered via websocket with messages that looks like:
232+
233+
```json
234+
{"Msg":"avrdude: verifying ...","ProgrammerStatus":"Busy"}
235+
{"Msg":"avrdude done. Thank you.","ProgrammerStatus":"Busy"}
236+
{"Flash":"Ok","ProgrammerStatus":"Done"}
237+
```
238+
239+
---
240+
241+
## Development
23242
24243
From the project root dir executing:
25244
```
@@ -96,4 +315,3 @@ By making a contribution to this project, I certify that:
96315
## Creating a release
97316
Just create a new release on github, and our drone server will build and upload
98317
ithe compiled binaries for every architecture in a zip file in the release itself.
99-

0 commit comments

Comments
 (0)