Skip to content

Commit 028b1b6

Browse files
rikkunessrikkuness
committed
improve documentation of the packet transfer protocol
1 parent f2332d8 commit 028b1b6

File tree

1 file changed

+38
-16
lines changed

1 file changed

+38
-16
lines changed

‎README_Protocol.md

Lines changed: 38 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,25 +24,47 @@ There are other codes added though:
2424
* 21 - Ctrl-u - delete line
2525
* 23 - Ctrl-w - delete word (currently just does the same as Ctrl-u)
2626

27-
### Packet Transfer
27+
## Packet Transfer
2828

29-
Added in 2v25:
29+
Added in 2v25. There is currently an implementation of this in https://github.com/espruino/EspruinoWebTools/blob/master/uart.js
3030

31-
```
32-
DLE[16],SOH[1],TYPE|LENHI,LENLO,DATA...
33-
```
31+
### Control Characters
3432

35-
If received or timed out (after 1s), will reply with an ACK[6] or NAK[21]
33+
Packet transfer is initiated by sending the `DOH`[ASCII 16] (Data Link Escape) control character, followed by the `SOH`[ASCII 1] (Start of Heading) control character.
3634

37-
TYPE is:
35+
### Heading Data
3836

39-
```
40-
PT_TYPE_RESPONSE = 0x0000, // Response to an EVAL packet
41-
PT_TYPE_EVAL = 0x2000, // execute and return the result as RESPONSE packet
42-
PT_TYPE_EVENT = 0x4000, // parse as JSON and create `E.on('packet', ...)` event
43-
PT_TYPE_FILE_SEND = 0x6000, // called before DATA, with {fn:"filename",s:123}
44-
PT_TYPE_DATA = 0x8000, // Sent after FILE_SEND with blocks of data for the file
45-
PT_TYPE_FILE_RECV = 0xA000 // receive a file - returns a series of PT_TYPE_DATA packets, with a final zero length packet to end
46-
```
37+
Following the initial control characters, the next two bytes signal the type and size of packet being sent. The first 3 bits contain the packet type, the following 13 represent an unsigned integer containing the byte length of the data that will follow.
4738

48-
There is currently an implementation of this in https://github.com/espruino/EspruinoWebTools/blob/master/uart.js
39+
| Packet Type | Hex Representation | 16 bit Binary Representation | Notes |
40+
| ------------- | ------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
41+
| `RESPONSE` | `0x0000` | `000-------------` | Response to an `EVAL` packet |
42+
| `EVAL` | `0x2000` | `001-------------` | Execute and return the result as `RESPONSE` packet |
43+
| `EVENT` | `0x4000` | `010-------------` | Parse data as JSON and create `E.on('packet', ...)` event |
44+
| `FILE_SEND` | `0x6000` | `011-------------` | Called before `DATA`, with `{fn:"filename",s:123}` |
45+
| `DATA` | `0x8000` | `100-------------` | Sent after `FILE_SEND` with blocks of data for the file |
46+
| `FILE_RECV` | `0xA000` | `101-------------` | Receive a file - returns a series of `DATA` packets, with a final zero length packet to end (calling data?) |
47+
| Length (low) | `0x0001` | `---0000000000001` | Minimum packet data length, 1 byte |
48+
| Length (high) | `0x1FFF` | `---1111111111111` | Maximum packet data length, 8191 bytes |
49+
50+
### Responses
51+
52+
Following transmission of a packet (or after timeout of 1 second), there will be one of two responses that signal successful or unsuccessful packet transmission.
53+
54+
| Type | ASCII character | Notes |
55+
| ------ | --------------- | --------------------------------------- |
56+
| `ACK` | 6 | Acknowledged successful receipt. |
57+
| `NACK` | 21 | Negative acknowledgement, unsuccessful. |
58+
59+
### Example
60+
61+
As an example, to create a file named `hello.txt` with the content `Hello World`, the packet is constructed as follows:
62+
63+
| Bytes | |
64+
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
65+
| `10 01` | DOH, SOH, control characters |
66+
| `60 19` | The `FILE_SEND` packet type is sent initially, and this initial packet will be 19 bytes. |
67+
| `7b 22 66 6e 22 3a 22 68 65 6c 6c 6f 2e 74 78 74 22 2c 22 73 22 3a 31 31 7d` | The data that follows is the 19 bytes that contain the JSON specifying which file to create, and that the file will be 11 bytes (the length of "Hello World") <br /> `{"fn":"hello.txt","s":11}` |
68+
| `10 01` | DOH, SOH, to start another packet transfer |
69+
| `80 11` | Signals this time that the packet type will be `DATA` and it will be 11 bytes. |
70+
| `48 65 6c 6c 6f 20 57 6f 72 6c 64` | The 11 bytes of data that contain the string `Hello World` |

0 commit comments

Comments
 (0)