Skip to content
This repository was archived by the owner on Mar 17, 2025. It is now read-only.

Commit d674692

Browse files
ed7coyneed7coyne
committed
Merge pull request #59 from ed7coyne/Serial
Add serial protocol
2 parents 6ca8f47 + e5570d6 commit d674692

File tree

1 file changed

+188
-0
lines changed

1 file changed

+188
-0
lines changed

‎serial_protocol.md

+188
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
#Protocol:
2+
During the first use, or when the chiplet changes environments a “NETWORK” call is expected to initialize the wifi parameters.
3+
4+
Every time a serial connection is established we will expect a “BEGIN” call after which any subsequent calls can be made, until the connection is closed.
5+
6+
In the following examples we use %% to represent variables. For example %Host% represents your firebase host.
7+
8+
##Response Format Byte
9+
All responses will be prefixed with one of the following bytes signifying the response type.
10+
```
11+
+ If response is ok and a raw string value.
12+
$ If response is ok, raw string value will be json formatted and prefixed by the byte count and a new line.
13+
: If response is ok and a number, this could be float or int.
14+
? If response is ok and a boolean value.
15+
- If response is an error
16+
```
17+
##NETWORK
18+
Only needs to be called when the chiplet is in a new environment and needs to connect to a new network. This setting will be stored by the chiplet and persisted through power cycles.
19+
###Usage
20+
NETWORK %SSID%
21+
NETWORK %SSID% %PASSWORD%
22+
###Response
23+
+CONNECTED - When connected to new network
24+
-UNABLE_TO_CONNECT - When unable to connect
25+
###Examples
26+
>> NETWORK home-guest
27+
<< +CONNECTED
28+
>> NETWORK home-private MySecretPassword
29+
<< +CONNECTED
30+
>> NETWORK home-guest
31+
<< -UNABLE_TO_CONNECT
32+
33+
##BEGIN
34+
Must be called after creating a Serial connection, it can take either just a host for accessing public variables or you may also provide a secret for accessing protected variables in the database.
35+
###Usage
36+
BEGIN %Host%
37+
BEGIN %Host% %Secret%
38+
###Response
39+
+OK - Accepted initialization parameters
40+
###Examples
41+
>> BEGIN https://samplechat.firebaseio-demo.com
42+
<< +OK
43+
>> BEGIN https://samplechat.firebaseio-demo.com nnz...sdf
44+
<< +OK
45+
##GET
46+
Fetches the value at %PATH% and returns it on the serial line. If %PATH% points to a leaf node you will get the raw value back, if it points to an internal node you will get a JSON string with all children.
47+
###Usage
48+
GET %PATH%
49+
###Response
50+
%DATA_AT_PATH%
51+
$%JSON_DATA_BYTE_COUNT% \r\n %JSON_DATA
52+
###Examples
53+
>>GET /user/aturing/first
54+
<<+Alan
55+
>>GET /user/aturing
56+
<<$39
57+
<<{ "first" : "Alan", "last" : "Turing" }
58+
59+
##GET{+,*,#,.,?,$}
60+
Same as GET but will either return the value in the format specified (by the format byte) or return an error.
61+
###Usage
62+
GET+ %PATH%
63+
GET: %PATH%
64+
GET? %PATH%
65+
GET$ %PATH%
66+
###Response
67+
%FORMATED_RESPONSE%
68+
###Examples
69+
>>GET? /user/aturing/was_human
70+
<<?true
71+
>>GET? /user/aturing/first
72+
<<-ERROR_INCORRECT_FORMAT
73+
##SET
74+
Store the data provided at the path provided. This method should be used for simple strings and will assume the first newline is the end of the data.
75+
###Usage
76+
SET %PATH% %DATA%
77+
###Response
78+
+OK
79+
-FAIL
80+
###Examples
81+
>>SET /user/aturing/first Alan
82+
<<+OK
83+
##SET$
84+
Similar to SET above but used to write multiline strings or raw binary data. Data format is similar to the batch string ($) return type, we specify the $DATA_BYTE_COUNT on the same line as SET$ then a newline and all data. However which the batch string ($) return type returns data json escaped and quoted you may provide raw data and we will handle the escaping.
85+
86+
Receiver will wait until a timeout for client to send %DATA_BYTE_COUNT% worth of data before becoming responsive again.
87+
###Usage
88+
SET$ %PATH%
89+
%DATA_BYTE_COUNT%
90+
%DATA%
91+
###Response
92+
+OK
93+
-FAIL
94+
-FAIL_TIMEOUT
95+
###Examples
96+
>>SET /user/aturing/address
97+
>>24
98+
>>78 High Street,
99+
>>Hampton
100+
<<+OK
101+
102+
##SET{+,*,#,.,?}
103+
Same as SET but will force the value to be stored in the given type or return an error if we cannot parse it as that type.
104+
###Usage
105+
SET+ %PATH% %VALUE%
106+
SET: %PATH% %VALUE%
107+
SET? %PATH% %VALUE%
108+
###Response
109+
+OK
110+
-INCORRECT_TYPE
111+
###Examples
112+
>>SET? /user/aturing/was_human true
113+
<<+OK
114+
>>SET? /user/aturing/was_human He was not a computer.
115+
<<-INCORRECT_TYPE
116+
117+
##REMOVE
118+
Deletes the value located at the path provided.
119+
###Usage
120+
REMOVE %PATH%
121+
###Response
122+
+OK
123+
-FAIL
124+
###Examples
125+
>>REMOVE /user/aturing
126+
<<+OK
127+
128+
##PUSH
129+
Adds a value to the list located at the path provided and returns the key at which the new object is located.
130+
###Usage
131+
PUSH %PATH% %DATA%
132+
###Response
133+
%KEY%
134+
###Examples
135+
>>PUSH /user/aturing/login_timestamps 1455052043
136+
<<+-K94eLnB0rAAvfkh_WC2
137+
138+
##PUSH$
139+
Similar to PUSH but used to write multiline strings or raw binary data. Data format is similar to the batch string ($) return type, we specify the $DATA_BYTE_COUNT on the same line as SET$ then a newline and all data. However you are not required to json escape all of your data, that will be handled for you.
140+
141+
Receiver will wait until a timeout for client to send $DATA_BYTE_COUNT worth of data before becoming responsive again.
142+
###Usage
143+
PUSH$ %PATH% %DATA_BYTE_COUNT%
144+
%DATA%
145+
###Response
146+
%KEY%
147+
###Examples
148+
>>PUSH$ /user/aturing/quotes 91
149+
>>We can only see a short distance ahead,
150+
>>but we can see plenty there that needs to be done.
151+
<<+-K94eLnB0rAAvfkh_WC3
152+
153+
##BEGIN_STREAM
154+
Used to register to receive a stream of events that occur to the object at the provided path.
155+
156+
After registering you will start receiving events on the response line. They will be formatted as one line with the event type {PUT,PATCH,etc..} followed by the sub_path that changed and the other line with the data associated with that event type. This data will be formatted similar to GET results and can have multi-line batch strings (*) or json strings (&).
157+
158+
The event stream will continue until you send END_STREAM.
159+
160+
When there is an ongoing event stream no other commands can be processed until you call END_STREAM as the event stream owns the return line.
161+
###Usage
162+
BEGIN_STREAM %PATH%
163+
###Response
164+
%EVENT_NAME% %SUB_PATH%
165+
%DATA%
166+
+OK
167+
###Examples
168+
>>BEGIN_STREAM /user/aturing
169+
<<+PUT /last_login
170+
<<:1455052043
171+
<<+PUT /address
172+
<<$24
173+
<<"78 High Street,\r\nHampton"
174+
175+
##END_STREAM
176+
Used to stop listening to events at a given path. This must be the same path provided to a previous BEGIN_STREAM call.
177+
178+
###Usage
179+
END_STREAM %PATH%
180+
###Response
181+
+OK
182+
-NOT_STREAMING_PATH
183+
###Examples
184+
>>END_STREAM /user/aturing
185+
<<-NOT_STREAMING_PATH
186+
>>BEGIN_STREAM /user/aturing
187+
>>END_STREAM /user/aturing
188+
<<+OK

0 commit comments

Comments
 (0)