#Protocol:

1.[General Protocol](#general-protocol)

2.[Database Protocol](#database-protocol)

3.[Messaging Protocol](#messaging-protocol)

#General Protocol:

During the first use, or when the chiplet changes environments a “NETWORK” call is expected to initialize the wifi parameters.

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.

<< +CONNECTED

>> NETWORK home-guest

<< -UNABLE_TO_CONNECT

#Database Protocol

##BEGIN

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.

##BEGIN_DB

Called to start communicating with the Firebase database, 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.

###Usage

BEGIN %Host%

BEGIN %Host% %Secret%

BEGIN_DB %Host%

BEGIN_DB %Host% %Secret%

###Response

+OK - Accepted initialization parameters

###Examples

>>BEGINhttps://samplechat.firebaseio-demo.com

>>BEGIN_DBhttps://samplechat.firebaseio-demo.com

<< +OK

>>BEGINhttps://samplechat.firebaseio-demo.com nnz...sdf

>>BEGIN_DBhttps://samplechat.firebaseio-demo.com nnz...sdf

<< +OK

##GET

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.

>>BEGIN_STREAM /user/aturing

>>END_STREAM /user/aturing

<<+OK

#Messaging Protocol

Called to start communicating with Firebase Cloud Messaging, it requires a server key. You can also optionally supply any of the arguments listed on the MSG command to make them the defaults for this session. If you set them as defaults you don't need to specify them when calling MSG.

###Usage

BEGIN_MSG %Server_Key% %Argument% %Argument% ...

###Response

+OK - Accepted initialization parameters

-ERROR_MISSING_SERVER_KEY

-ERROR_PARSING_ARGUMENTS

###Examples

>> BEGIN_MSG AIzaSyCk4GtbBa-XMQbc5TyT5oe1KnH71M-2lAZ

<< +OK

>> BEGIN_MSG AIzaSyCk4GtbBa-XMQbc5TyT5oe1KnH71M-2lAZ topic=iot_updates high_priority=true time_to_live=3600

<< +OK

>> BEGIN_MSG

<< +ERROR_MISSING_SERVER_KEY

>> BEGIN_MSG AIzaSyCk4GtbBa-XMQbc5TyT5oe1KnH71M-2lAZ topic = iot_updates

<< +ERROR_PARSING_ARGUMENTS // Can't have spaces in arguments.

Called to start composing a message. It is followed by a list of named arguments, all of these arguments may be listed on BEGIN_MSG as well to set them as defaults for the session. Even if they are listed on BEGIN_MSG they can be overriden when calling MSG.

Named arguments are specified by " %name%=%value% " where neither names nor values will have spaces in them.

This is a comma separated list of device registrations you wish to send the message to. The list can have between 1 and 100 ids in it so you can send to a single device this way too.

registration_ids=fQCLfBOGdh0...9k0,fQCLfBOGdh0...5j1

This is a comma separated list of device registrations you wish to send the message to. The list can have between 1 and 100 ids in it so you can send to a single device this way too.

registration_ids=fQCLfBOGdh0...9k0,fQCLfBOGdh0...5j1

This is the name of a topic you wish to send the message to.

topic=news

Sets a collapse key on the message. When the server recieves a message with a collapse key it will discard any pending messages it has with the same key. So the client will only see the most recent one when it checks in.

collapse_key=LatestUpdate

Can be "true" or "false". If set to true the user's device will wake up to receive the message. This is used when the message is high priority but a cost it paid in battery life for the user.

high_priority=true

Can be "true" or "false". If set to true the message will not be delivered until the user's device is active. This is used when the message can wait to be seen until the user is available.

delay_while_idle=false

The message will expire after this amount of time in seconds. The default (and max value) is four weeks. Can be between 0 and 2,419,200.

time_to_live=500

##Usage

MSG %Argument% %Argument% ...

###Response

+OK - Ready to specify rest of message.

-ERROR_MISSING_TARGET - You didn't specify either registration_ids or topic.

-ERROR_PARSING_ARGUMENTS - There was a syntax error in your arguments.

-ERROR_INVALID_ARGUMENT - You specified an argument we don't support.

###Examples

>> MSG

<< +OK // Only works if you specified a default registration_ids or topic on BEGIN_MSG.

>> MSG

<< +ERROR_MISSING_TARGET // If you didn't specify a default registration_ids or topic on BEGIN_MSG.

>> MSG registration_ids=fQCLfBOGdh0...9k0,fQCLfBOGdh0...5j1 delay_while_idle=true

<< +OK

>> MSG registration_ids=fQCLfBOGdh0...9k0, fQCLfBOGdh0...5j1 delay_while_idle=true

<< +ERROR_PARSING_ARGUMENTS // There is a space in the list of registration ids.

>> MSG some_random_thing=true

<< +ERROR_INVALID_ARGUMENT // some_random_thing is not a valid argument.

Notification to display to the user, is made up of a title and a body. The title is specified on the first line and the first line ends with a count of bytes in the body. We will then read the next %Body_Byte_Count% bytes (after the line break) and interpret them as the body. If there is no body specify 0 for the byte count. The count must be the last thing on the line, it cannot end in whitespace.

##Usage

NOTIFICATION %Title% %Body_Byte_Count%

%Body%

###Response

+OK - Ready to specify rest of message.

-ERROR_INCORRECT_FORMAT - The message format was incorrect.

-ERROR_NOT_ENOUGH_DATA_FOR_BODY - We did not receive the specified amount of data for the body.

###Examples

>> NOTIFICATION This is a test. 0

<< +OK

>> NOTIFICATION This is a test.

<< -ERROR_INCORRECT_FORMAT

>> NOTIFICATION This is a test with a body. 12

>> Hello World!

<< +OK

>> NOTIFICATION This is a test with a body. 12

>> Hello Worl

<< -ERROR_NOT_ENOUGH_DATA_FOR_BODY

Data to deliver to client application. This is comprised of Key->Value pairs. The Key is specified on the first line and the first line ends with a count of bytes in the value. We will then read the next %Value_Byte_Count% bytes (after the line break) and interpret them as the value. If there is no value specify 0 forthe byte count. The count must be the last thing on the line, it cannot end in whitespace.

##Usage

ADD_DATA %KEY% %VALUE_BYTE_COUNT%

%VALUE%

###Response

+OK - Ready to specify rest of message.

-ERROR_INCORRECT_FORMAT - The message format was incorrect.

-ERROR_NOT_ENOUGH_DATA_FOR_BODY - We did not receive the specified amount of data for the body.

###Examples

>> ADD_DATA Temperature_Ready 0

<< +OK

>> ADD_DATA Temperature_Ready

<< -ERROR_INCORRECT_FORMAT

>> ADD_DATA Temperature 3

>> 104

<< +OK

>> ADD_DATA Temperature 3

>> 10

<< -ERROR_NOT_ENOUGH_DATA_FOR_BODY

Send the message we have been preparing.

##Usage

SEND_MSG

###Response

+OK - Message Sent.

-FAIL - Failed to send message, we still have the message prepared so you may retry.

###Examples

>> SEND_MSG

<< +OK

>> SEND_MSG

<< -FAIL