This document provides details of the API available in the BlocklyProp Launcher. These calls are available through a websocket interface. The client system should send API requests as JSON packet messages. These messages are listed here and described below.
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.
type - "hello-browser" (Required)
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)
- Deprecated: Another baud rate setting is required, specific to the terminal/graph in the serial-terminal message; specification via "hello-browser" is ignored.
{
"type": "hello-browser"
}Example:
const apiUrl = 'ws://localhost:6009';
connection = new WebSocket(apiUrl);
// Callback executed when the connection is opened
connection.onopen = function(event) {
// Create a Hello message
const wsMessage = {
type: 'hello-browser'
};
// Send the message to the API
connection.send(JSON.stringify(wsMessage));
};The BP Launcher responds to the "hello-browser" request with a "hello-client" message containing the following elements:
type - "hello-client" (Required).
version - The semantic version of the BP Launcher (major, minor, patch) (Required)
api - The version of the API used by this BP Launcher (major only) (optional; omission means API v1)
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)
{
"type": "hello-client",
"version": "1.0.4",
"api": "2",
"b64Msg": "true"
}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).
type - "load-prop" (Required)
action - "RAM" or "EEPROM" (Required)
portPath - target port's name (direct from the port drop-down list); wired or wireless port. (Required)
- 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).
payload - An (always base-64) encoded .elf, .binary, or .eeprom data image containing the Propeller Application. (Required)
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. (Required)
{
"type": "load-prop",
"action": "RAM",
"portPath": "<device_name>",
"payload": "D4F2A34AB...",
"debug": "none"
}The BP Launcher responds to the "load-prop" request with numerous messages to indicate status or to command UI display changes.
type - "ui-command" (Required).
action - "message-compile", "open-terminal", "open-graph", or "close-compile" (Required).
msg - "." (deprecated), or "\r" + a descriptive string of text, indicating milestone moments in the download process. (Required only during "message-compile" actions)
- "." 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.
- "\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.
{
"type": "ui-command",
"action": "message-compile",
"msg": "\r002-Downloading"
}--or--
{
"type": "ui-command",
"action": "open-terminal"
}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.
type - "serial-terminal" (Required)
action - "open", "close", or "msg" indicates to open port, close port, or transmit data from the client to the Propeller over port portPath. (Required)
portPath - Target port's name (direct from the port drop-down list); wired or wireless port. (Required)
baudrate - Set the desired baud rate for serial communications with the Propeller device. The default value is 115200. (Optional)
msg - Contains data message to transmit to Propeller. (Required only when action is "msg".)
Examples:
Open Terminal Session:
const messageToSend = {
type: 'serial-terminal',
action: 'open',
outTo: 'terminal',
portPath: "selected_com_port",
baudrate: 115200,
msg: 'none'
};
// The connection variable is assumed to hold a valid open websocket handle
// Send the message to the BP Launcher
connection.send(JSON.stringify(messageToSend));Open Graph Session:
const message = {
type: 'serial-terminal',
action: 'open',
outTo: 'graph',
portPath: "selected_com_port",
baudrate: 9600,
msg: 'none'
};
// The connection variable is assumed to hold a valid open websocket handle
// Send the message to the BP Launcher
connection.send(JSON.stringify(message));The BP Launcher may respond to an "open" or "msg" action.
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.
- NOTE: The action element is not populated for this error.
{
"type": "serial-terminal",
"msg": "Port '<port_name>' not found.\rPlease close this terminal and select an existing port."
}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)".
If the open operation fails, the BP Launcher sends a "serial-terminal" type message to the client containing the error in msg.
- NOTE: The action element is not populated for this error.
{
"type": "serial-terminal",
"msg": "Failed to connect.\rPlease close this terminal and select a connected port."
}The BP Launcher does not respond to the client for a "close" action; it simply handles the request silently.
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.
type - "serial-terminal" (Required)
packetID - An increasing value that uniquely identifies the message packet. (Required)
msg - Contains base-64 encoded data from the Propeller. (Required)
{
"type": "serial-terminal",
"packetID": <1, 2, 3, etc.>,
"msg": <b64-encoded_data>
}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.
type - "port-list-request" (Required)
Example:
// Request a port list from the server
const message = {
type: 'port-list-request'
};
connection.send(JSON.stringify(message));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.
type - "pref-port" (Required)
portPath - port's name (direct from the port drop-down list); wired or wireless port. (Required)
Example:
this.activeConnection.send(JSON.stringify({
type: 'pref-port',
portPath: portName,
}));