Skip to content

Commit 3a72ac0

Browse files
authored
Merge pull request #127 from PropGit/master
Updated API.md from source.
2 parents ce1c1aa + 667cc20 commit 3a72ac0

File tree

3 files changed

+137
-61
lines changed

3 files changed

+137
-61
lines changed

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,3 +75,6 @@ Thumbs.db
7575

7676
# Mac finder files
7777
.DS_Store
78+
79+
# Ultra Edit files
80+
*.bak

API.md

Lines changed: 133 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -7,39 +7,28 @@ messages. These messages are listed here and described below.
77
* [Load Propeller](#load-propeller-message)
88
* [Serial Terminal](#serial-terminal-message)
99
* [Port List](#port-list-message)
10-
* [Port Preference](#port-preference-message)
10+
* [Preferred Port](#preferred-port-message)
1111

1212

1313
## Open Channel <a name="open-channel-message"></a>
14-
When the websocket is established, this message initializes the channel that all subsequent interactions with the APU will use. This message also facilitates reception of the version of BlocklyProp Launcher that the client is speaking to.
14+
When the websocket is established, this message initializes the channel that all subsequent interactions with the API will use. This message also facilitates reception of the version of BlocklyProp Launcher that the client is speaking to.
1515

16-
### Message elements
17-
**type** - Message name, "hello-browser". (**Required**)
16+
### Send (client -> Launcher)
1817

19-
**baud** - Select a baud rate that the BlocklyProp Launcher will use to communicate with attached Propeller device(s).The default value is 115200. (Optional and deprecated)
18+
**type** - "hello-browser" (**Required**)
19+
20+
**baudrate** - Select a baud rate that the BlocklyProp Launcher will use to communicate with attached Propeller device(s).The default value is 115200. (Optional and deprecated)
21+
22+
- Deprecated: Another baud rate setting is required, specific to the terminal/graph in the <a href="#serial-terminal-message">serial-terminal</a> message; specification via "hello-browser" is ignored.
2023

21-
Note that there is another baud rate setting, specific to the terminal/graph, in the <a href="#serial-terminal-message">serial-terminal</a> message; thus specification vis "hello-browser" is not necessary.
2224
```json
2325
{
24-
"type": "hello-browser",
25-
"baud": "115200"
26+
"type": "hello-browser"
2627
}
2728
```
28-
The BP Launcher responds to this request with a 'hello-client' message containing the following elements:
29-
30-
**type** - A text string containing 'hello-client' (**Required**).
31-
32-
**version** - The semantic version of the BP Launcher (major, minor, patch) (**Required**)
3329

34-
**rxBase64** - A boolean flag indicating that the BP Launcher is capable of receiving base64-encoded serial streams. (**Required**)
35-
```json
36-
{
37-
"type": "hello-client",
38-
"version": "1.0.4",
39-
"rxBase64": "true"
40-
}
41-
```
4230
Example:
31+
4332
```javascript
4433
const apiUrl = 'ws://localhost:6009';
4534
connection = new WebSocket(apiUrl);
@@ -49,59 +38,105 @@ Example:
4938

5039
// Create a Hello message
5140
const wsMessage = {
52-
type: 'hello-browser',
53-
baud: '115200',
41+
type: 'hello-browser'
5442
};
5543

5644
// Send the message to the API
5745
connection.send(JSON.stringify(wsMessage));
5846
};
5947
```
6048

49+
### Receive (client <- Launcher)
50+
The BP Launcher responds to the "hello-browser" request with a "hello-client" message containing the following elements:
51+
52+
**type** - "hello-client" (**Required**).
53+
54+
**version** - The semantic version of the BP Launcher (major, minor, patch) (**Required**)
55+
56+
**api** - The version of the API used by this BP Launcher (major only) (optional; omission means API v1)
57+
58+
**b64Msg** - [future API] A boolean flag indicating that BP Launcher requires all _msg_ and _payload_ elements (both received and sent) as base64-encoded serial streams. (optional; omission means "false," only some _msg_ and _payload_ elements are base64-encoded)
59+
60+
```json
61+
{
62+
"type": "hello-client",
63+
"version": "1.0.4",
64+
"api": "2",
65+
"b64Msg": "true"
66+
}
67+
```
6168

6269
## Load Propeller <a name="load-propeller-message"></a>
63-
The client sends this message when it wants to download a Propeller Application to the connected
64-
Propeller device, storing the app in either RAM or EEPROM (which is really RAM & EEPROM together)
70+
The client sends this message when it wants to download a Propeller Application to the connected Propeller device, storing the app in either RAM or EEPROM (which is really RAM & EEPROM together).
71+
72+
### Send (client -> Launcher)
6573

66-
### Message elements
6774
**type** - "load-prop" (**Required**)
6875

6976
**action** - "RAM" or "EEPROM" (**Required**)
7077

7178
**portPath** - target port's name (direct from the port drop-down list); wired or wireless port. (**Required**)
79+
- The client's port drop-down list contents is filled by BP Launcher and any one of those exact values is what BP Launcher expects back (in the portPath element) to indicate the target port. Old (pre API v1) versions included the port's path and port's name but has since been simplified to only port name. Regardless, the element name remains as _portPath_ and client must send the exact value direct from the port drop-down item in any case).
7280

73-
_Needs Review:_
74-
75-
_The portPath value can be any of the following; 'enumerated port name from the client's OS', 'The wireless SSID', or 'wired'? Not sure about that and loadPropeller() is equally ambiguous._
81+
**payload** - An (always base-64) encoded .elf, .binary, or .eeprom data image containing the Propeller Application. (**Required**)
7682

77-
**payload** - A base-64 encoded .elf, .binary, or .eeprom data containing the Propeller Application image. (**Required**)
83+
**debug** - "none", "term", or "graph". If set to "term" or "graph" then a terminal or graphing display (respectively) is intended to connect to the Propeller after download.
84+
(**Required**)
7885

79-
**debug** - set to 'true' if a terminal is intended to connect to the Propeller after download, otherwise set to false. Default is false. (Optional)
8086
```json
8187
{
8288
"type": "load-prop",
8389
"action": "RAM",
84-
"portPath": "device_name",
90+
"portPath": "<device_name>",
8591
"payload": "D4F2A34AB...",
86-
"debug": "false"
92+
"debug": "none"
93+
}
94+
```
95+
96+
### Receive (client <- Launcher)
97+
The BP Launcher responds to the "load-prop" request with numerous messages to indicate status or to command UI display changes.
98+
99+
**type** - "ui-command" (**Required**).
100+
101+
**action** - "message-compile", "open-terminal", "open-graph", or "close-compile" (**Required**).
102+
103+
**msg** - "." (deprecated), or "\r" + a descriptive string of text, indicating milestone moments in the download process. (**Required** only during "message-compile" _actions_)
104+
- "." indicates a progressive step in the download process meant only as an _activity_ indicator on the UI. This functionality is meant for older (pre v1.0?) versions of the client and is deprecated.
105+
- "\r" + descriptive text indicates download operation status in the form ###-message where ### is a 3-digit ID that uniquely indicates the category and intent of the _message_.
106+
107+
```json
108+
{
109+
"type": "ui-command",
110+
"action": "message-compile",
111+
"msg": "\r002-Downloading"
112+
}
113+
```
114+
--or--
115+
```json
116+
{
117+
"type": "ui-command",
118+
"action": "open-terminal"
87119
}
88120
```
89121

90122

91123
## Serial Terminal <a name="serial-terminal-message"></a>
92-
The client sends this message to open or close a terminal serial stream, or to transmit data serially to
93-
the Propeller on a specified port at a specific baud rate.
124+
The client sends this message to open or close a port for serial data destined for a terminal or graphing display, or to transmit data serially to the Propeller on a specified port at a specific baud rate. The Propeller also sends messages of this type to communicate serial data to the client.
125+
126+
### Send (client -> Launcher)
94127

95128
**type** - "serial-terminal" (**Required**)
96129

97-
**action** - One of \["open", "close", or "msg"\] which opens port, closes port, or transmits data
98-
from the client to the Propeller over port \[portPath\]. (**Required**)
130+
**action** - "open", "close", or "msg" indicates to open port, close port, or transmit data
131+
from the client to the Propeller over port _portPath_. (**Required**)
99132

100133
**portPath** - Target port's name (direct from the port drop-down list); wired or wireless port. (**Required**)
101134

102135
**baudrate** - Set the desired baud rate for serial communications with the Propeller device. The default value is 115200. (Optional)
103136

104-
**msg** - Contains data message to transmit to Propeller. (**Required**only when the action element is set to "msg".)
137+
**msg** - Contains data message to transmit to Propeller. (**Required** only when _action_ is "msg".)
138+
139+
Examples:
105140

106141
Open Terminal Session:
107142
```javascript
@@ -135,52 +170,90 @@ Open Graph Session:
135170
connection.send(JSON.stringify(message));
136171
```
137172

138-
## Port List <a name="port-list-message"></a>
139-
The client sends this message to get a current list of ports that the Launcher sees on the system.
140-
This causes Launcher to send the list immediately, but also starts a process in the Launcher that
141-
automatically transmits a port-list-response message every 5 seconds.
173+
### Receive (client <- Launcher)
174+
The BP Launcher may respond to an "open" or "msg" _action_.
142175

143-
_Needs Review:_
144-
_This update continues until the BP Launcher receives another "port-list-request" message with a single response directive or the websocket connection is closed._
145-
_Also questioning if the **msg** element has any other options. Otherwise, it appears to be redundant._
176+
#### Response to Any Action With Port Issue:
177+
Any "serial-terminal" _type_ message that specifies a _portPath_ to an invalid port results in a response message sent back to the client of "serial-terminal" _type_ with the error in the _msg_ element.
178+
- NOTE: The _action_ element is not populated for this error.
146179

147-
**type** - "port-list-request" (**Required**)
180+
```json
181+
{
182+
"type": "serial-terminal",
183+
"msg": "Port '<port_name>' not found.\rPlease close this terminal and select an existing port."
184+
}
185+
```
186+
187+
#### Response to "open" Action:
188+
If the open operation is successful, the BP Launcher will not respond directly; however, the open channel to the Propeller usually results in one or more "serial-terminal" _type_ messages carrying Propeller data back to the client. See ["Receive (client <- Launcher <- Propeller)"](receive-from-propeller).
189+
190+
If the open operation fails, the BP Launcher sends a "serial-terminal" _type_ message to the client containing the error in _msg_.
191+
- NOTE: The _action_ element is not populated for this error.
192+
193+
```json
194+
{
195+
"type": "serial-terminal",
196+
"msg": "Failed to connect.\rPlease close this terminal and select a connected port."
197+
}
198+
```
199+
200+
#### Response to "close" Action:
201+
The BP Launcher does not respond to the client for a "close" _action_; it simply handles the request silently.
202+
203+
#### Response to "msg" Action:
204+
The BP Launcher does not directly respond to the client for a "msg" _action_ - it simply sends the _msg_ data to the Propeller; however, the Propeller may respond to that data, through the BP Launcher, as indicated below.
205+
206+
### Receive (client <- Launcher <- Propeller) <a name="receive-from-propeller"></a>
207+
When a port is open for terminal or graph use, data from the Propeller is sent through the BP Launcher to the client using a "serial-terminal" _type_ message. This message as a _packetID_ element and a _msg_ element.
148208

149-
**msg** - "port-list-request" (**Required**)
209+
**type** - "serial-terminal" (**Required**)
210+
211+
**packetID** - An increasing value that uniquely identifies the message packet. (**Required**)
212+
213+
**msg** - Contains base-64 encoded data from the Propeller. (**Required**)
214+
215+
```json
216+
{
217+
"type": "serial-terminal",
218+
"packetID": <1, 2, 3, etc.>,
219+
"msg": <b64-encoded_data>
220+
}
221+
```
222+
223+
## Port List <a name="port-list-message"></a>
224+
The client sends this message to get a current list of ports that the Launcher sees on the system. This causes Launcher to send the list immediately, but also starts a process in the Launcher that automatically transmits a port-list-response message every 5 seconds. This update continues until the BP Launcher sees that the websocket connection is closed.
225+
226+
**type** - "port-list-request" (**Required**)
150227

151228
Example:
152229
```javascript
153230
// Request a port list from the server
154231
const message = {
155-
type: 'port-list-request',
156-
msg: 'port-list-request',
232+
type: 'port-list-request'
157233
};
158234

159235
connection.send(JSON.stringify(message));
160236
```
161237

162-
## Port Preference <a name="port-preference-message"></a>
238+
## Preferred Port <a name="preferred-port-message"></a>
239+
The client sends this message when the user has selected a new port in the port drop-down list. "New" port means a port that wasn't already selected immediately before the user's action.
240+
241+
**type** - "pref-port" (**Required**)
163242

243+
**portPath** - port's name (direct from the port drop-down list); wired or wireless port. (**Required**)
244+
245+
Example:
164246
```javascript
165247
this.activeConnection.send(JSON.stringify({
166248
type: 'pref-port',
167249
portPath: portName,
168250
}));
169251
```
252+
170253
<!--
171-
Launcher Version request
172-
type: "hello-browser"
173-
baudrate: (optional, defaults to 115200 but is actually unused by Launcher in this case)
174254
Debug Clear To Send request
175255
NOT SUPPORTED; believe the intention was to halt Launcher to Solo "serial" transmissions until Solo is ready to receive
176256
type: "debug-cts"
177-
This process of exploring what the communication looks like is beneficial for me too. It was defined long ago, partly by Michele and partly by Matt, during the initial design and later websocket support design. I've made some changes on the Client and Launcher sides, and very little changes on the BlocklyProp side; just what was needed to match. It's starting to "come back" to me now.
178-
179-
Something I think Solo (BlocklyProp too, of course) does is request the port list on a timed basis, sending more and more requests to the Launcher; however, the Launcher automatically sends the list on a timed basis once the first request for the list is made on the websocket.
180-
181-
Over the websocket channel, BlocklyProp Launcher sends JSON packet messages to Solo as described below:
182-
183-
Serial Terminal data (from Propeller to Solo)
184257
-->
185258

186259
[Top of page](#page-top)

loader.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ function loadPropeller(sock, portName, action, payload, debug) {
101101
portName is wired or wireless port's name
102102
action is 'RAM' or 'EEPROM'
103103
payload is base-64 encoded .elf, .binary, or .eeprom data containing the Propeller Application image
104-
debug is true if a terminal is intended to connect to the Propeller after download; false otherwise*/
104+
debug is "none", "term", or "graph". "term" or "graph" if a terminal or graphing display (respectively) is intended to connect to the Propeller after download.*/
105105

106106
let binImage;
107107

0 commit comments

Comments
 (0)