You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -7,39 +7,28 @@ messages. These messages are listed here and described below.
7
7
*[Load Propeller](#load-propeller-message)
8
8
*[Serial Terminal](#serial-terminal-message)
9
9
*[Port List](#port-list-message)
10
-
*[Port Preference](#port-preference-message)
10
+
*[Preferred Port](#preferred-port-message)
11
11
12
12
13
13
## Open Channel <aname="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.
**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 <ahref="#serial-terminal-message">serial-terminal</a> message; specification via "hello-browser" is ignored.
20
23
21
-
Note that there is another baud rate setting, specific to the terminal/graph, in the <ahref="#serial-terminal-message">serial-terminal</a> message; thus specification vis "hello-browser" is not necessary.
22
24
```json
23
25
{
24
-
"type": "hello-browser",
25
-
"baud": "115200"
26
+
"type": "hello-browser"
26
27
}
27
28
```
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**)
33
29
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
-
```
42
30
Example:
31
+
43
32
```javascript
44
33
constapiUrl='ws://localhost:6009';
45
34
connection =newWebSocket(apiUrl);
@@ -49,59 +38,105 @@ Example:
49
38
50
39
// Create a Hello message
51
40
constwsMessage= {
52
-
type:'hello-browser',
53
-
baud:'115200',
41
+
type:'hello-browser'
54
42
};
55
43
56
44
// Send the message to the API
57
45
connection.send(JSON.stringify(wsMessage));
58
46
};
59
47
```
60
48
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)
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)
65
73
66
-
### Message elements
67
74
**type** - "load-prop" (**Required**)
68
75
69
76
**action** - "RAM" or "EEPROM" (**Required**)
70
77
71
78
**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).
72
80
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**)
76
82
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**)
78
85
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)
80
86
```json
81
87
{
82
88
"type": "load-prop",
83
89
"action": "RAM",
84
-
"portPath": "device_name",
90
+
"portPath": "<device_name>",
85
91
"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"
87
119
}
88
120
```
89
121
90
122
91
123
## Serial Terminal <aname="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)
94
127
95
128
**type** - "serial-terminal" (**Required**)
96
129
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**)
99
132
100
133
**portPath** - Target port's name (direct from the port drop-down list); wired or wireless port. (**Required**)
101
134
102
135
**baudrate** - Set the desired baud rate for serial communications with the Propeller device. The default value is 115200. (Optional)
103
136
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:
105
140
106
141
Open Terminal Session:
107
142
```javascript
@@ -135,52 +170,90 @@ Open Graph Session:
135
170
connection.send(JSON.stringify(message));
136
171
```
137
172
138
-
## Port List <aname="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_.
142
175
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.
146
179
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.
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.
148
208
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 <aname="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**)
150
227
151
228
Example:
152
229
```javascript
153
230
// Request a port list from the server
154
231
constmessage= {
155
-
type:'port-list-request',
156
-
msg:'port-list-request',
232
+
type:'port-list-request'
157
233
};
158
234
159
235
connection.send(JSON.stringify(message));
160
236
```
161
237
162
-
## Port Preference <aname="port-preference-message"></a>
238
+
## Preferred Port <aname="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**)
163
242
243
+
**portPath** - port's name (direct from the port drop-down list); wired or wireless port. (**Required**)
244
+
245
+
Example:
164
246
```javascript
165
247
this.activeConnection.send(JSON.stringify({
166
248
type:'pref-port',
167
249
portPath: portName,
168
250
}));
169
251
```
252
+
170
253
<!--
171
-
Launcher Version request
172
-
type: "hello-browser"
173
-
baudrate: (optional, defaults to 115200 but is actually unused by Launcher in this case)
174
254
Debug Clear To Send request
175
255
NOT SUPPORTED; believe the intention was to halt Launcher to Solo "serial" transmissions until Solo is ready to receive
176
256
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:
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.*/
0 commit comments