Skip to content
/ arduino-create-agent Public

[EDITOR-523] Update README.md #607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Feb 3, 2021
+36 −443
Merged

[EDITOR-523] Update README.md #607

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2df8981
removed old download links
umbynos Jan 26, 2021
a29a380
move to https://github.com/arduino/arduino-create-agent/wiki/Advanced…
umbynos Feb 1, 2021
eb1f41b
move to https://github.com/arduino/arduino-create-agent/wiki/Disable-…
umbynos Feb 1, 2021
e350ddb
move to https://github.com/arduino/arduino-create-agent/wiki/How-to-u…
umbynos Feb 1, 2021
13cdfd7
move to https://github.com/arduino/arduino-create-agent/wiki/Develope…
umbynos Feb 1, 2021
c07e3a7
add Documentation pointing to wiki and other improvements
umbynos Feb 1, 2021
17f01d7
add architecture scheme
umbynos Feb 1, 2021
94718c6
Update README.md
Feb 2, 2021
b28fa68
applied suggestions from @smellai
umbynos Feb 2, 2021
ce228b6
fix minor typos
umbynos Feb 2, 2021
0618c32
add notice on apple m1 support
umbynos Feb 3, 2021
f10c7e3
update issue template with architecture
umbynos Feb 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Original file line number Diff line number Diff line change
@@ -20,6 +20,7 @@ about: Create a report to help us improve
- Browser [e.g. chrome, safari]:
- Browser Version:
- Agent Version [e.g. 1.0.0]:
- CPU architecture [e.g. amd64]

## Additional context
<!--Add any other context about the problem here.-->
478 changes: 35 additions & 443 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -3,453 +3,44 @@
arduino-create-agent
====================

The Arduino Create Agent is a single binary that will sit on the traybar and work in the background. It allows you to use the [Arduino Create applications](https://create.arduino.cc) to seamlessly upload code to any USB connected Arduino board (or Yún in LAN) directly from the browser.

## GOA 2 refactoring
The agent is currently transitioning to the v2 of the GOA framework for API management, please refer to the following
[documentation](https://github.com/goadesign/goa/tree/v2) in order to install tools and libraries


i.e. to regenerate code from design use:
```bash
goa gen github.com/arduino/arduino-create-agent/design
```

## Installation
Get the latest version of the Agent for all supported platforms:

### Windows
* [Windows with Edge](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-windows-installer-edge.exe)
* [Windows with Chrome](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-windows-installer-chrome.exe)
* [Windows with Firefox](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-windows-installer-firefox.exe)

### MacOSX
* [MacOSX with Safari](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-osx-installer-safari.dmg)
* [MacOSX with Chrome](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-osx-installer-chrome.dmg)
* [MacOSX with Firefox](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-osx-installer-firefox.dmg)

### Linux
* [Linux x64 with Chrome](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-linux-x64-installer-chrome.tar.gz)
* [Linux x64 with Firefox](https://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-linux-x64-installer-firefox.tar.gz)

arduino-create-agent is a fork of @[johnlauer](https://github.com/johnlauer)'s [serial-port-json-server](https://github.com/johnlauer/serial-port-json-server) (which we really want to thank for his kindness and great work)

The history has been rewritten to keep the repo small (thus removing all binaries committed in the past)



## Using multiple configurations

The agent supports multiple configuration files. When multiple configurations are found by the agent, the tray icon menu is expanded to contain the different configurations:

![Agent multiple configuration tray icon](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/linux/tray-icon-multiple-profiles.png)

The default `config.ini` file contains common configurations, every other config file inherit from it.

To create multiple configuration files:
- stop the agent: tray bar icon -> pause then tray bar icon -> kill
- find the `config.ini` file that is present in the `arduino-create-agent` installation folder
- copy `config.ini` or create a new ini file (e.g. `example.ini`) with content:
```ini
name = your configuration name
```
add in this file other configuration options (you can override inherited values from `config.ini`)
- restart the agent
- click the tray bar icon and select the new configuration

**Tip**: you can also use the multiple configurations feature to create a new configuration with the proxy settings. This way you can have multiple proxies configured and disable proxy configuration with ease.

## When behind a proxy

The agent supports working behind a proxy, but manual configuration is required (there is no support for automatic proxy discovery).

To add proxy configuration:
- stop the agent: tray bar icon -> pause then tray bar icon -> kill
- find the `config.ini` file that is present in the `arduino-create-agent` installation folder
- copy `config.ini` to a new file (e.g. `proxy.ini`) with content:
```ini
name = Proxy Enabled
[env]
http_proxy=your.proxy.here
https_proxy=your.https.proxyhere
```
- please note spaces are not allowed before and after the string `http_proxy`
- restart the agent
- select the proper Proxy profile as in the image
- your agent will now work behind a proxy

![Agent multiple configuration tray icon](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/linux/tray-icon-multiple-profiles.png)


## Disable Autostart

### Windows
1. Type "Task Manager in the Windows Search Bar"

![Type "Task Manager in the Windows Search Bar"](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/windows/01.png)
2. Select the Startup tab

![Select the Startup tab](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/windows/02.png)
3. Select the autostart file

![Select the autostart file](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/windows/03.png)
4. Disable it

![Disable it](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/windows/04.png)

### Mac OSX
1. Open Finder, click on Go menu, select 'Go to Folder'

![Open Finder, click on Go menu, select 'Go to Folder'](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/mac/01.png)
2. Type the directory containing the autolauncher file, change <username> with your Mac username, by default the directory is /Users/username/Library/LaunchAgents

![Type the directory containing the autolauncher file, change <username> with your Mac username, by default the directory is /Users/username/Library/LaunchAgents](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/mac/02.png)
3. Select the ArduinoCreateAgent.plist file

![Select the ArduinoCreateAgent.plist file](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/mac/03.png)
4. Right click on the file name and select 'Move to Trash'

![Right click on the file name and select 'Move to Trash'](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/mac/04.png)

---
The command line way:
```
$ launchctl unload ~/Library/LaunchAgents/ArduinoCreateAgent.plist
```
### Linux
1. Show hidden files
![Show hidden files](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/linux/01.png)
2. Select the .config dir in your home
![Select the .config dir in your home](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/linux/02.png)
3. Select the autostart dir
![Select the autostart dir](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/linux/03.png)
4. Move the file to the trash
![Move the file to the trash](https://raw.githubusercontent.com/arduino/arduino-create-agent/devel/images/linux/04.png)
---
The command line way:
Just remove the autostart file in your desktop manager, in Ubuntu is:
```
$ rm $HOME/.config/autostart/arduino-create-agent.desktop
```
To start manually the agent you can open the file at:
```
$ nohup $HOME/ArduinoCreateAgent-1.1/Arduino_Create_Bridge &
```
or in the location selected during the installation
# Contributing
Please use the current latest version:
### Windows
* [Windows with Edge dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-windows-installer-edge.exe)
* [Windows with Chrome dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-windows-installer.exe)
* [Windows with Firefox dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-windows-installer-firefox.exe)
### MacOSX
* [MacOSX with Safari dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-osx-installer-safari.dmg)
* [MacOSX with Chrome dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-osx-installer-chrome.dmg)
* [MacOSX with Firefox dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-osx-installer-firefox.dmg)
### Linux
* [Linux x64 with Chrome dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-linux-x64-installer-chrome.run)
* [Linux x64 with Firefox dev](https://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-linux-x64-installer-firefox.run)
## How to use it
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 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](https://cdnjs.cloudflare.com/ajax/libs/socket.io/1.3.5/socket.io.min.js) to handle the messages.
Once you have the websocket endpoint you need you can:
```javascript
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:

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

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

You will receive a message like:

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

or

```json
{
"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:

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

or


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

```json
{"Cmd":"Queued","QCnt":1,"Ids":[""],"D":["hello"],"Port":"/dev/ttyACM0"}
{"Cmd":"Write","QCnt":0,"Id":"","P":"/dev/ttyACM0"}
{"Cmd":"CompleteFake","Id":"","P":"/dev/ttyACM0"}
## Architecture
```

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

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

```json
{
"DownloadStatus": "Success",
"Msg":"Map Updated"
}
+-------------------------------+
| |
| Browser |
| | Web socket +----------------------+ flashes +---------------+
| +---------------------------+ |<-------------->| +------------>| |
| | | | | Arduino Create Agent | | Arduino Board |
| | Arduino Create Web Editor | +--------------->| |<------------+ |
| | | | REST API +----------------------+ serial +---------------+
| +---------------------------+ |
+-------------------------------+
```

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:

```json
{
"board":"arduino:avr:leonardo",
"port":"/dev/ttyACM1",
"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\"",
"signature":"97db97ced2c",
"hex":"OjEwMDAwMDAwMEM5NEU1MDAwQzk0MEQwMTBDOTQwRDAxMEM5NDBEMDE2MQ0KOjEwMDAxMDAwMEM5NDBEMDEwQzk0M",
"filename":"Blink.ino.hex",
"extrafiles": [],
"extra":{
"auth":{
"username":null,
"password":null,
"private_key":null,
"port":null
},
"wait_for_upload_port":true,
"use_1200bps_touch":true,
"network":false,
}
}
```

- 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:

```json
{"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](https://github.com/arduino/arduino-create-agent-js-client) in your client application

---

## Development

Please remember that for compile the project, you need go version >= 1.10.x (older versions are not supported for compile)

To clone the repository, run the following command:
```
go get github.com/arduino/arduino-create-agent
```

This will clone the repository into your [Go workspace](https://golang.org/doc/code.html#Workspaces) or create a new workspace, if one doesn't exist. You can set `$GOPATH` to define where your Go workspace is located.

Now you can go to the project directory and compile it:
```
cd $GOPATH/src/github.com/arduino/arduino-create-agent
go build
```

This will create the `arduino-create-agent` binary.

Other prerequisites are:
* libappindicator (Linux only on Ubuntu `sudo apt-get install libappindicator1 libappindicator3-0.1-cil libappindicator3-0.1-cil-dev libappindicator3-1 libappindicator3-dev libgtk-3-0 libgtk-3-dev`)
* [go-selfupdate] (https://github.com/sanbornm/go-selfupdate) if you want to test automatic updates

### Windows
Since we are using the https://github.com/lxn/walk library, we need to ship a manifest.xml file, otherwise the error would be:

```
panic: Unable to create main window: TTM_ADDTOOL failed
```

To do it make sure to install the required tool:

```
$ go get github.com/akavel/rsrc
```

and build it with

```
$ rsrc -arch=386 -manifest=manifest.xml
$ go build
```

Keep in mind that the presence of rsrc.syso file will break other builds, for example
## Installation
Get the [latest version](https://github.com/arduino/arduino-create-agent/releases) of the Agent for all supported platforms or complete the [Getting Started](https://create.arduino.cc/getting-started/plugin/welcome).

```
$ GOOS=linux go build
# github.com/arduino/arduino-create-agent
/usr/lib/go/pkg/tool/linux_amd64/link: running gcc failed: exit status 1
/usr/sbin/ld: i386 architecture of input file `/tmp/go-link-084341451/000000.o' is incompatible with i386:x86-64 output
collect2: error: ld returned 1 exit status
```
## Apple M1 support
At the moment the new Apple Silicon Macs released in November 2020, like the new [MacBook Pro 13"](https://www.apple.com/macbook-pro-13/), [MacBook Air](https://www.apple.com/macbook-air/) and [Mac mini](https://www.apple.com/mac-mini/) models with the [Apple M1](https://www.apple.com/mac/m1/) chip are currently NOT supported by the Create Agent.

## Submitting an issue
## Documentation
The documentation has been moved to the [wiki](https://github.com/arduino/arduino-create-agent/wiki) page. There you can find:
- [Advanced usage](https://github.com/arduino/arduino-create-agent/wiki/Advanced-usage): explaining how to use multiple configurations and how to use the agent with a proxy.
- [Agent Beta Program](https://github.com/arduino/arduino-create-agent/wiki/Agent-Beta-Program)
- [Developement](https://github.com/arduino/arduino-create-agent/wiki/Developement): containing useful info to help in development
- [Disable Autostart](https://github.com/arduino/arduino-create-agent/wiki/Disable-Autostart)
- [How to compile on Raspberry Pi](https://github.com/arduino/arduino-create-agent/wiki/How-to-compile-on-Raspberry-Pi)
- [How to use crashreport functionality](https://github.com/arduino/arduino-create-agent/wiki/How-to-use-crashreport-functionality)
- [How to use the agent](https://github.com/arduino/arduino-create-agent/wiki/How-to-use-the-agent)

Please attach the output of the commands running at the debug console if useful.
## Contributing
### Submitting an issue

## Submitting a pull request
When submitting a new issue please search for duplicates before creating a new one. Help us by providing useful context and information. Please attach the output of the commands running at the debug console or attach [crash reports](https://github.com/arduino/arduino-create-agent/wiki/How-to-use-crashreport-functionality) if useful.

### Submitting a pull request
We are glad you want to contribute with code: that's the best way to help this software.

Your contribution is adding or modifying existing behaviour, please always refer to an existing issue or open a new one before contributing. We are trying to use [Test Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) in the near future: please add one or more tests that prove that your contribution is good and is working as expected, it will help us a lot.
@@ -460,6 +51,12 @@ Also, for your contribution to be accepted, every one of your commits must be "S

By signing off your commits, you agree to the following agreement, also known as [Developer Certificate of Origin](http://developercertificate.org/): it assures everyone that the code you're submitting is yours or that you have rights to submit it.

## Authors and acknowledgment
arduino-create-agent is a fork of @[johnlauer](https://github.com/johnlauer)'s [serial-port-json-server](https://github.com/johnlauer/serial-port-json-server) (which we really want to thank for his kindness and great work)

The history has been rewritten to keep the repo small (thus removing all binaries committed in the past)

## License
```
Developer Certificate of Origin
Version 1.1
@@ -498,8 +95,3 @@ By making a contribution to this project, I certify that:
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```


## Creating a release
Just create a new release on GitHub, and our drone server will build and upload
the compiled binaries for every architecture in a zip file in the release itself.