Skip to content

Made this repo a library #1

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.

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 20 commits into from
Jul 19, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion .github/workflows/test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,4 @@ jobs:
go-version: "1.16"

- name: Build
run: task build
run: task build-dummy-discovery
245 changes: 1 addition & 244 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,250 +1,7 @@
# Arduino pluggabe discovery reference implementation

The `dummy-discovery` tool is a command line program that interacts via stdio. It accepts commands as plain ASCII strings terminated with LF `\n` and sends response as JSON.
# A golang library to handle the Arduino pluggable-discovery communication protocol.

## How to build

Install a recent go enviroment and run `go build`. The executable `dummy-discovery` will be produced in your working directory.

## Usage

After startup, the tool waits for commands. The available commands are: `HELLO`, `START`, `STOP`, `QUIT`, `LIST` and `START_SYNC`.

#### HELLO command

The `HELLO` command is used to establish the pluggable discovery protocol between client and discovery.
The format of the command is:

`HELLO <PROTOCOL_VERSION> "<USER_AGENT>"`

for example:

`HELLO 1 "Arduino IDE"`

or:

`HELLO 1 "arduino-cli"`

in this case the protocol version requested by the client is `1` (at the moment of writing there were no other revisions of the protocol).
The response to the command is:

```json
{
"eventType": "hello",
"protocolVersion": 1,
"message": "OK"
}
```

`protocolVersion` is the protocol version that the discovery is going to use in the remainder of the communication.

#### START command

The `START` starts the internal subroutines of the discovery that looks for ports. This command must be called before `LIST` or `START_SYNC`. The response to the start command is:

```json
{
"eventType": "start",
"message": "OK"
}
```

#### STOP command

The `STOP` command stops the discovery internal subroutines and free some resources. This command should be called if the client wants to pause the discovery for a while. The response to the stop command is:

```json
{
"eventType": "stop",
"message": "OK"
}
```

#### QUIT command

The `QUIT` command terminates the discovery. The response to quit is:

```json
{
"eventType": "quit",
"message": "OK"
}
```

after this output the tool quits.

#### LIST command

The `LIST` command returns a list of the currently available serial ports. The format of the response is the following:

```json
{
"eventType": "list",
"ports": [
{
"address": "1",
"label": "Dummy upload port",
"protocol": "dummy",
"protocolLabel": "Dummy protocol",
"properties": {
"mac": "73622384782",
"pid": "0x0041",
"vid": "0x2341"
}
}
]
}
```

#### START_SYNC command

The `START_SYNC` command puts the tool in "events" mode: the discovery will send `add` and `remove` events each time a new port is detected or removed respectively.
The immediate response to the command is:

```json
{
"eventType": "start_sync",
"message": "OK"
}
```

after that the discovery enters in "events" mode.

The `add` events looks like the following:

```json

"eventType": "add",
"port": {
"address": "4",
"label": "Dummy upload port",
"protocol": "dummy",
"protocolLabel": "Dummy protocol",
"properties": {
"mac": "294489539128",
"pid": "0x0041",
"vid": "0x2341"
}
}
}
```

it basically gather the same information as the `list` event but for a single port. After calling `START_SYNC` a bunch of `add` events may be generated in sequence to report all the ports available at the moment of the start.

The `remove` event looks like this:

```json
{
"eventType": "remove",
"port": {
"address": "4",
"protocol": "dummy"
}
}
```

in this case only the `address` and `protocol` fields are reported.

### Example of usage

A possible transcript of the discovery usage:

```
HELLO 1 "arduino-cli"
{
"eventType": "hello",
"message": "OK",
"protocolVersion": 1
}
START
{
"eventType": "start",
"message": "OK"
}
LIST
{
"eventType": "list",
"ports": [
{
"address": "1",
"label": "Dummy upload port",
"protocol": "dummy",
"protocolLabel": "Dummy protocol",
"properties": {
"mac": "73622384782",
"pid": "0x0041",
"vid": "0x2341"
}
}
]
}
STOP
{
"eventType": "stop",
"message": "OK"
}
START_SYNC
{
"eventType": "start_sync",
"message": "OK"
}
{
"eventType": "add",
"port": {
"address": "2",
"label": "Dummy upload port",
"protocol": "dummy",
"protocolLabel": "Dummy protocol",
"properties": {
"mac": "147244769564",
"pid": "0x0041",
"vid": "0x2341"
}
}
}
{
"eventType": "add",
"port": {
"address": "3",
"label": "Dummy upload port",
"protocol": "dummy",
"protocolLabel": "Dummy protocol",
"properties": {
"mac": "220867154346",
"pid": "0x0041",
"vid": "0x2341"
}
}
}
{
"eventType": "add",
"port": {
"address": "4",
"label": "Dummy upload port",
"protocol": "dummy",
"protocolLabel": "Dummy protocol",
"properties": {
"mac": "294489539128",
"pid": "0x0041",
"vid": "0x2341"
}
}
}
{
"eventType": "remove",
"port": {
"address": "4",
"protocol": "dummy"
}
}
QUIT
{
"eventType": "quit",
"message": "OK"
}
$
```

## Security

If you think you found a vulnerability or other security-related bug in this project, please read our
Expand Down
10 changes: 5 additions & 5 deletions Taskfile.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
version: "3"

tasks:
build:
desc: Build the project
build-dummy-discovery:
desc: Build the dummy-discovery client example
cmds:
- go build -v -ldflags '{{.LDFLAGS}}'
- go build -o dist/dummy-discovery -v -ldflags '{{.LDFLAGS}}' ./dummy-discovery

vars:
PROJECT_NAME: "dummy-discovery"
Expand All @@ -14,5 +14,5 @@ vars:
TIMESTAMP:
sh: echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
LDFLAGS: >
-X github.com/arduino/dummy-discovery/version.Tag={{.VERSION}}
-X github.com/arduino/dummy-discovery/version.Timestamp={{.TIMESTAMP}}
-X github.com/arduino/pluggable-discovery-protocol-handler/dummy-discovery/args.Tag={{.VERSION}}
-X github.com/arduino/pluggable-discovery-protocol-handler/dummy-discovery/args.Timestamp={{.TIMESTAMP}}
Loading