Skip to content

Commit 6350eb5

Browse files
fstasifstasi
committed
updated readme
1 parent 974dd80 commit 6350eb5

File tree

1 file changed

+121
-29
lines changed

1 file changed

+121
-29
lines changed

‎README.md

+121-29
Original file line numberDiff line numberDiff line change
@@ -16,57 +16,149 @@ The application is designed to be as agnostic as possible regarding how and wher
1616

1717
- As soon as the application is bootstrapped it reads the [URL parameters](#config-parameters) and uses them to set the initial state and create the WebSocket connection
1818
- When the WebSocket connection is created, data points are collected, parsed, and printed to the chart
19-
- The app can also send messages back to the boards via WebSocket
19+
- The app can also send messages and change some configuration sending appropriate commands via WebSocket
2020

2121
### Config Parameters
2222

2323
The Serial Plotter Web App is initialized by passing a number of parameters in the URL, in the form of a QueryString (eg: http://localhost:3000?currentBaudrate=2400&baudrates=300,1200,2400,4800,9600,19200,38400,57600,74880,115200,230400,250000,500000,1000000,2000000&darkTheme=true&wsPort=5000&connected=true&interpolate=true&generate=true).
2424

25-
| Name | Description | Type (default) |
26-
|-|-|-|
27-
| `currentBaudrate` | currently selected baudrate | Number(9600)|
28-
| `currentLineEnding` | currently selected line ending | String("\r\n")|
29-
| `baudrates` | populate the baudrates menu | String[]/Comma separated strings ([])|
30-
| `darkTheme` | whether to use the dark version of the plotter | Boolean(false) |
31-
| `wsPort` | websocket port used for communication | Number(3030) |
32-
| `interpolate` | whether to smooth the graph or not | Boolean(false) |
33-
| `serialPort` | name of the serial port the data is coming from | String("") |
34-
| `connected` | whether if the serial port is connected or not| Boolean(false) |
35-
| `generate` | generate fake datapoints to print random charts (dev purposes only)| Boolean(false) |
3625

37-
It is possible to update the state of the serial plotter by sending the above parameters via WebSocket in the form of a JSON-stringified object, using the `MIDDLEWARE_CONFIG_CHANGED` [Command](#websocket-communication-protocol).
26+
It is possible to update the state of the serial plotter by sending configuration via WebSocket in the form of a JSON-stringified object see the [Command](#websocket-communication-protocol) section below.
3827

3928
### Websocket Communication Protocol
4029

4130
Besides the initial configuration, which is passed in via URL parameters, the communication between the app and the middleware is implemented over WebSocket.
4231

43-
It's possible to send a JSON-stringified message from and to the Serial Plotter App, as long as it adheres to the following format:
32+
It's possible to send JSON-stringified messages between the Serial Plotter App and the Middleware, as long as they adhere to the following format:
4433

4534
```
4635
{
47-
"command": <a valid command, see below>,
48-
"data": <the value for the command>
36+
command: <a valid command, see below>,
37+
data: <the value for the command>
4938
}
5039
```
5140

52-
The command/data fields follow the specification:
41+
There are 4 different messages that can be sent/received:
5342

54-
| Command Field | Data field format | Initiator | Description |
55-
|-|-|-|-|
56-
| "PLOTTER_SET_BAUDRATE" | number | Serial Plotter | request the middleware to change the baudrate |
57-
| "PLOTTER_SET_LINE_ENDING" | string | Serial Plotter| request the middleware to change the lineending for the messages sent from the middleware to the board |
58-
| "PLOTTER_SEND_MESSAGE" | text | Serial Plotter | send a message to the middleware. The message will be sent over to the board |
59-
| "PLOTTER_SET_INTERPOLATE" | boolean | Serial Plotter | send the interpolation flag to the Middleware |
60-
| "MIDDLEWARE_CONFIG_CHANGED" | Object (see [config parameters](#config-parameters) ) | Middleware | Send an updated configuration from the middleware to the Serial Plotter. Used to update the state, eg: changing the color theme at runtime |
43+
1. **Data Messages**: a message sent from the Middleware to the Serial Plotter App. This is the actual data received by the pluggable monitor that needs to be displayed in the Serial Plotter App.
6144

62-
Example of a message ready to be sent from the Serial Plotter App to the Middleware
45+
example:
46+
```
47+
{
48+
command: "", // empty
49+
data: string[] // the data received from the pluggable monitor
50+
}
51+
```
6352
64-
```typescript
65-
const websocketMessage = JSON.stringify({command: "PLOTTER_SET_BAUDRATE", data: 9600})
66-
```
53+
2. **Middleware Commands**: a command sent from the server to the Serial Plotter App to communicate a change in the settings
54+
55+
example:
56+
```
57+
{
58+
command: "ON_SETTINGS_DID_CHANGE",
59+
data: Partial<MonitorSettings> // see section below
60+
}
61+
```
62+
63+
3. **Client Commands - Send Message**: a command sent by the client to deliver a string to the connected board
64+
65+
example:
66+
```
67+
{
68+
command: "SEND_MESSAGE",
69+
data: string
70+
}
71+
```
72+
73+
4. **Client Commands - Change Settings**: a command sent by the client to change some settings in the UI or in the connected board
74+
75+
example:
76+
```
77+
{
78+
command: "CHANGE_SETTINGS",
79+
data: Partial<MonitorSettings> // see section below
80+
}
81+
```
6782
68-
**NOTE: For performance sake, the raw data coming from the serial port that is sent by the middleware to the serial plotter has to be a stringified array of values, rather than the Command/Data object**
83+
#### Monitor Settings
84+
85+
Settings changes, sent and received in the Serial Plotter App, must follow the following object structure
86+
87+
```
88+
Partial<MonitorSettings> = {
89+
pluggableMonitorSettings: PluggableMonitorSettings;
90+
monitorUISettings: Partial<MonitorModelState>;
91+
}
92+
```
6993
94+
That means a Setting Message can container `pluggableMonitorSettings` and/or `monitorUISettings`.
95+
96+
Let's take a look at the difference between the two:
97+
98+
1. **pluggableMonitorSettings**: a map of settings specific for the board attached to the pluggable monitor. Since every board has different capabilities, the settings are different and the structure is a map of key/value pairs. The `value` is an object with the following structure:
99+
100+
```
101+
{
102+
// The setting identifier
103+
readonly id?: string;
104+
// A human-readable label of the setting (to be displayed on the GUI)
105+
readonly label?: string;
106+
// The setting type (at the moment only "enum" is available)
107+
readonly type?: string;
108+
// The values allowed on "enum" types
109+
readonly values?: string[];
110+
// The selected value
111+
selectedValue: string;
112+
}
113+
```
114+
115+
example:
116+
```
117+
pluggableMonitorSettings: {
118+
baudrate: {
119+
id: "baudrate",
120+
label: "Baudrate",
121+
type: "enum",
122+
values: ["300","9600", "115200"],
123+
selectedValue: "9600"
124+
},
125+
otherSetting: {
126+
id: "otherSetting",
127+
label: "Other Setting",
128+
type: "enum",
129+
values: ["A","B", "C"],
130+
selectedValue: "B"
131+
}
132+
}
133+
134+
```
135+
136+
2. **monitorUISettings**: settings that are used in the UIs of the Serial Plotter App.
137+
These are sent to the middleware to be stored and propagated to other clients.
138+
139+
When a client connected to the same websocket change one of the following settings, the change should be stored in the backend (for future re-use) and immediately propagated to all connected clients in order to update their UIs.
140+
141+
`monitorUISettings` is an object with the following structure:
142+
```
143+
{
144+
// used by the serial monitors to stick at the bottom of the window
145+
autoscroll: boolean;
146+
// used by the serial monitors to show the timestamp next to the actual data
147+
timestamp: boolean;
148+
// used by the clients to store the information about the last EOL used when sending a message to the board
149+
lineEnding: EOL;
150+
// used by the Serial Plotter App to interpolate the chart
151+
interpolate: boolean;
152+
// the theme the user choosed
153+
darkTheme: boolean;
154+
// the current websocket port where the communication happens
155+
wsPort: number;
156+
// the port the pluggable monitor in the middleware is connected to
157+
serialPort: string;
158+
// the connection status of the pluggable monitor to the actual board
159+
connected: boolean;
160+
}
161+
```
70162
71163
## Development
72164

0 commit comments

Comments
 (0)