|
| 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 | +>> BEGINhttps://samplechat.firebaseio-demo.com |
| 42 | +<< +OK |
| 43 | +>> BEGINhttps://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 |