Skip to content

Correct example commands and output in README to reflect actual behavior of tool #16

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 1 commit into from
May 25, 2022
Merged

Correct example commands and output in README to reflect actual behavior of tool #16

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
211 changes: 154 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ The response to the command is:
```json
{
"eventType": "hello",
"protocolVersion": 1,
"message": "OK"
"message": "OK",
"protocolVersion": 1
}
```

Expand All @@ -42,17 +42,18 @@ The response to the command is:

The `DESCRIBE` command returns a description of the communication port. The description will have metadata about the port configuration, and which parameters are available:

<!-- prettier-ignore -->
```json
{
"event": "describe",
"message": "ok",
"eventType": "describe",
"message": "OK",
"port_description": {
"protocol": "serial",
"configuration_parameters": {
"baudrate": {
"label": "Baudrate",
"type": "enum",
"values": [
"value": [
"300",
"600",
"750",
Expand All @@ -73,22 +74,38 @@ The `DESCRIBE` command returns a description of the communication port. The desc
],
"selected": "9600"
},
"parity": {
"label": "Parity",
"type": "enum",
"values": ["None", "Even", "Odd", "Mark", "Space"],
"selected": "None"
},
"bits": {
"label": "Data bits",
"type": "enum",
"values": ["5", "6", "7", "8", "9"],
"value": [
"5",
"6",
"7",
"8",
"9"
],
"selected": "8"
},
"parity": {
"label": "Parity",
"type": "enum",
"value": [
"None",
"Even",
"Odd",
"Mark",
"Space"
],
"selected": "None"
},
"stop_bits": {
"label": "Stop bits",
"type": "enum",
"values": ["1", "1.5", "2"],
"value": [
"1",
"1.5",
"2"
],
"selected": "1"
}
}
Expand All @@ -100,7 +117,7 @@ Each parameter has a unique name (`baudrate`, `parity`, etc...), a `type` (in th

The parameter name can not contain spaces, and the allowed characters in the name are alphanumerics, underscore `_`, dot `.`, and dash `-`.

The `enum` types must have a list of possible `values`.
The `enum` types must have a list of possible `value`.

The client/IDE may expose these configuration values to the user via a config file or a GUI, in this case the `label` field may be used for a user readable description of the parameter.

Expand All @@ -114,18 +131,18 @@ The response to the command is:

```JSON
{
"event": "configure",
"message": "ok",
"eventType": "configure",
"message": "OK"
}
```

or if there is an error:

```JSON
{
"event": "configure",
"error": true,
"message": "invalid value for parameter baudrate: 123456"
"eventType": "configure",
"message": "invalid value for parameter baudrate: 123456",
"error": true
}
```

Expand All @@ -150,16 +167,16 @@ The answer to the `OPEN` command is:

```JSON
{
"event": "open",
"message": "ok"
"eventType": "open",
"message": "OK"
}
```

If the monitor tool cannot communicate with the board, or if the tool can not connect back to the TCP port, or if any other error condition happens:

```JSON
{
"event": "open",
"eventType": "open",
"error": true,
"message": "unknown port /dev/ttyACM23"
}
Expand All @@ -171,17 +188,19 @@ Once the port is opened, it may be unexpectedly closed at any time due to hardwa

```JSON
{
"event": "port_closed",
"message": "serial port disappeared!"
"eventType": "port_closed",
"message": "serial port disappeared!",
"error": true
}
```

or

```JSON
{
"event": "port_closed",
"message": "lost TCP/IP connection with the client!"
"eventType": "port_closed",
"message": "lost TCP/IP connection with the client!",
"error": true
}
```

Expand All @@ -191,16 +210,16 @@ The `CLOSE` command will close the currently opened port and close the TCP/IP co

```JSON
{
"event": "close",
"message": "ok"
"eventType": "close",
"message": "OK"
}
```

or in case of error

```JSON
{
"event": "close",
"eventType": "close",
"error": true,
"message": "port already closed"
}
Expand All @@ -227,7 +246,7 @@ If the client sends an invalid or malformed command, the monitor should answer w
{
"eventType": "command_error",
"error": true,
"message": "Unknown command XXXX"
"message": "Command XXXX not supported"
}
```

Expand All @@ -247,33 +266,70 @@ DESCRIBE
"eventType": "describe",
"message": "OK",
"port_description": {
"protocol": "test",
"protocol": "serial",
"configuration_parameters": {
"echo": {
"label": "echo",
"type": "enum",
"value": [
"on",
"off"
],
"selected": "on"
},
"speed": {
"baudrate": {
"label": "Baudrate",
"type": "enum",
"value": [
"300",
"600",
"750",
"1200",
"2400",
"4800",
"9600",
"19200",
"38400",
"57600",
"115200"
"115200",
"230400",
"460800",
"500000",
"921600",
"1000000",
"2000000"
],
"selected": "9600"
},
"bits": {
"label": "Data bits",
"type": "enum",
"value": [
"5",
"6",
"7",
"8",
"9"
],
"selected": "8"
},
"parity": {
"label": "Parity",
"type": "enum",
"value": [
"None",
"Even",
"Odd",
"Mark",
"Space"
],
"selected": "None"
},
"stop_bits": {
"label": "Stop bits",
"type": "enum",
"value": [
"1",
"1.5",
"2"
],
"selected": "1"
}
}
}
}
CONFIGURE speed 19200
CONFIGURE baudrate 19200
{
"eventType": "configure",
"message": "OK"
Expand All @@ -283,33 +339,70 @@ DESCRIBE
"eventType": "describe",
"message": "OK",
"port_description": {
"protocol": "test",
"protocol": "serial",
"configuration_parameters": {
"echo": {
"label": "echo",
"type": "enum",
"value": [
"on",
"off"
],
"selected": "on"
},
"speed": {
"baudrate": {
"label": "Baudrate",
"type": "enum",
"value": [
"300",
"600",
"750",
"1200",
"2400",
"4800",
"9600",
"19200",
"38400",
"57600",
"115200"
"115200",
"230400",
"460800",
"500000",
"921600",
"1000000",
"2000000"
],
"selected": "19200"
},
"bits": {
"label": "Data bits",
"type": "enum",
"value": [
"5",
"6",
"7",
"8",
"9"
],
"selected": "8"
},
"parity": {
"label": "Parity",
"type": "enum",
"value": [
"None",
"Even",
"Odd",
"Mark",
"Space"
],
"selected": "None"
},
"stop_bits": {
"label": "Stop bits",
"type": "enum",
"value": [
"1",
"1.5",
"2"
],
"selected": "1"
}
}
}
}
OPEN 127.0.0.1:5678 "test"
OPEN 127.0.0.1:5678 /dev/ttyACM0
{
"eventType": "open",
"message": "OK"
Expand All @@ -320,10 +413,14 @@ CLOSE
"message": "OK"
}
QUIT
{
"eventType": "quit",
"message": "OK"
}
$
```

On another terminal tab to test it you can run `nc -l -p 5678` before running the `OPEN 127.0.0.1:5678 "test"` command. After that you can write messages in that terminal tab and see them being echoed.
On another terminal tab to test it you can run `nc -l -p 5678` before running the `OPEN 127.0.0.1:5678 /dev/ttyACM0` command. After that you can write messages in that terminal tab and see them being echoed.

## Security

Expand Down