<commit_before>arduino-create-agent
====================

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

* [Windows](http://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-windows-installer.exe)
* [MacOSX](http://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-osx-installer.dmg)
* [Linux x64](http://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-linux-x64-installer.run)

arduino-create-agent is a fork of @johnlauer's 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)

## Disable Autostart

### Windows
1. ![Type "Task Manager in the Windows Searchbar" ](https://github.com/arduino/arduino-create-agent/master/images/windows/01.png)
2. ![Select the .config dir in your home](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/windows/02.png)
3. ![Select the autostart dir](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/windows/03.png)
4. ![Move the file to the trash](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/windows/04.png)
2. Find the Arduino 

### Mac OSX

### Linux
Visual way:
1. ![Show hidden files](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/linux/01.png)
2. ![Select the .config dir in your home](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/linux/02.png)
3. ![Select the autostart dir](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/linux/03.png)
4. ![Move the file to the trash](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/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 dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-windows-installer.exe)
* [MacOSX dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-osx-installer.dmg)
* [Linux x64 dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-linux-x64-installer.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://localhost:8990/info
    curl: (7) Failed to connect to localhost port 8990: Connection refused
    $ curl http://localhost:8991/info
    
    $ curl http://localhost:8992/info
    {"http":"http://localhost:8992","https":"https://localhost:8991","version":"1.0.36","ws":"ws://localhost:8992","wss":"wss://localhost: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('message', yourCommand);

    socket.on('message', 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:

```javascript
socket.emit('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"}
```

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

    download avrdude

receiving a reply like

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

### 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\" {upload.verbose} -patmega32u4 -cavr109 -P{serial.port} -b57600 -D \"-Uflash:w:{build.path}/{build.project_name}.hex:i\"",
  "signature":"97db97ced2c",
  "hex":"OjEwMDAwMDAwMEM5NEU1MDAwQzk0MEQwMTBDOTQwRDAxMEM5NDBEMDE2MQ0KOjEwMDAxMDAwMEM5NDBEMDEwQzk0M",
  "filename":"Blink.ino.hex",
  "extra":{
    "auth":{
      "password":<PASSWORD>
    },
    "wait_for_upload_port":true,
    "use_1200bps_touch":true,
    "network":false,
    "params_verbose":"-v",
    "params_quiet":"-q -q",
    "verbose":true
  }
}
```

- commandline is the command to execute to perform the upload. This is for example avrdude on a leonardo.

- hex contains the sketch hex encoded in base64

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

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

---

## Development

From the project root dir executing:
```
export GOPATH=$PWD
go get
go build
```
will build the `arduino-create-agent` binary.

`compile_webidebridge.sh` contains the cross-platform script we use to deploy the agent for all the supported platforms; it needs to be adjusted as per your `go` installation paths and OS.

You can use `bootstrapPlatforms` function to compile the needed CGO-enabled environment

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

## Submitting an issue

Please attach the output of the commands running at the debug console 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 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.

Be sure to use `go vet` and `go fmt` on every file before each commit: it ensures your code is properly formatted.

Also, for your contribution to be accepted, everyone of your commits must be "Signed-off". This is done by commiting using this command: `git commit --signoff`

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.

```
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    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
ithe compiled binaries for every architecture in a zip file in the release itself.
<commit_msg>Mac OS instructions to disable autostart<commit_after>arduino-create-agent
====================

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

* [Windows](http://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-windows-installer.exe)
* [MacOSX](http://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-osx-installer.dmg)
* [Linux x64](http://downloads.arduino.cc/CreateBridgeStable/ArduinoCreateAgent-1.1-linux-x64-installer.run)

arduino-create-agent is a fork of @johnlauer's 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)

## Disable Autostart

### Windows
1. ![Type "Task Manager in the Windows Search Bar"](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/windows/01.png)
2. ![Select the .config dir in your home](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/windows/02.png)
3. ![Select the autostart dir](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/windows/03.png)
4. ![Move the file to the trash](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/windows/04.png)
2. Find the Arduino 

### Mac OSX
1. ![Open the Go menu on Finder](https://github.com/arduino/arduino-create-agent/master/images/mac/01.png)
2. ![Type the directory containing the autolauncher file, change <username> with your Mac username](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/mac/02.png)
3. ![Select the ArduinoCreateAgent.plist file](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/mac/03.png)
4. ![Move the file to the trash](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/mac/04.png)
2. Find the Arduino 
---
The command line way:
```
$ launchctl unload ~/Library/LaunchAgents/ArduinoCreateAgent.plist
```

### Linux
Visual way:
1. ![Show hidden files](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/linux/01.png)
2. ![Select the .config dir in your home](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/linux/02.png)
3. ![Select the autostart dir](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/images/linux/03.png)
4. ![Move the file to the trash](https://raw.githubusercontent.com/arduino/arduino-create-agent/master/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 dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-windows-installer.exe)
* [MacOSX dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-osx-installer.dmg)
* [Linux x64 dev](http://downloads.arduino.cc/CreateBridge/staging/ArduinoCreateAgent-1.0-linux-x64-installer.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://localhost:8990/info
    curl: (7) Failed to connect to localhost port 8990: Connection refused
    $ curl http://localhost:8991/info
    
    $ curl http://localhost:8992/info
    {"http":"http://localhost:8992","https":"https://localhost:8991","version":"1.0.36","ws":"ws://localhost:8992","wss":"wss://localhost: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('message', yourCommand);

    socket.on('message', 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:

```javascript
socket.emit('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"}
```

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

    download avrdude

receiving a reply like

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

### 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\" {upload.verbose} -patmega32u4 -cavr109 -P{serial.port} -b57600 -D \"-Uflash:w:{build.path}/{build.project_name}.hex:i\"",
  "signature":"97db97ced2c",
  "hex":"OjEwMDAwMDAwMEM5NEU1MDAwQzk0MEQwMTBDOTQwRDAxMEM5NDBEMDE2MQ0KOjEwMDAxMDAwMEM5NDBEMDEwQzk0M",
  "filename":"Blink.ino.hex",
  "extra":{
    "auth":{
      "password":<PASSWORD>
    },
    "wait_for_upload_port":true,
    "use_1200bps_touch":true,
    "network":false,
    "params_verbose":"-v",
    "params_quiet":"-q -q",
    "verbose":true
  }
}
```

- commandline is the command to execute to perform the upload. This is for example avrdude on a leonardo.

- hex contains the sketch hex encoded in base64

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

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

---

## Development

From the project root dir executing:
```
export GOPATH=$PWD
go get
go build
```
will build the `arduino-create-agent` binary.

`compile_webidebridge.sh` contains the cross-platform script we use to deploy the agent for all the supported platforms; it needs to be adjusted as per your `go` installation paths and OS.

You can use `bootstrapPlatforms` function to compile the needed CGO-enabled environment

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

## Submitting an issue

Please attach the output of the commands running at the debug console 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 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.

Be sure to use `go vet` and `go fmt` on every file before each commit: it ensures your code is properly formatted.

Also, for your contribution to be accepted, everyone of your commits must be "Signed-off". This is done by commiting using this command: `git commit --signoff`

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.

```
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
660 York Street, Suite 102,
San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    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
ithe compiled binaries for every architecture in a zip file in the release itself.

{'fraction_non_alphanumeric': 0.11973819301848049, 'fraction_numerical': 0.01954996577686516, 'mean_word_length': 4.144586267605634, 'pattern_counts': {'":': 164, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 28, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 30, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2382464', 'n_tokens_mistral': 7625, 'n_tokens_neox': 7091, 'n_words': 2555}