-
Notifications
You must be signed in to change notification settings - Fork 2
Network Protocol (There And Back Again, A Packet's Tale)
The communication between the Webfront and the backend is central to this whole thing working. For brevity's sake, I'll keep this page rather short and focus on only what matters.
The backend is listening on port 11211 for incoming UDP packets. It is looking for something like this:
[64-character Service Master Key][Other stuff]
The 64-character SMK must match AF19914DFE944E38FE8CED6E490D1BB16C6A20F7F36237753A2EAF5BF2503536, otherwise the request will not be serviced. (That's the default key - change it before you deploy! See the Testing vs. Release section on the main page.) [Other Stuff] can be anything, but it must fit within the buffer which is currently 1024 bytes long (-1 for the null terminator, -64 for the SMK = 959 usable bytes per packet).
Ideally, [Other stuff] will consist of some kind of "opcode" and then parameters, which will be interpreted specifically for that "opcode".
It's probably important to mention that this isn't a purely ASCII protocol, even if it looks like it in some places - we do use binary encodings for some things, like opcodes...
Opcodes are 4 characters long (but not necessarily printable characters - they can use any of the 2^32 possible binary encodings for those bits). Implemented opcodes are listed below (big-endian). Unlike the API parameters, the parameter name (key) is not transmitted in these exchanges. Just the raw data, of fixed length, displayed in parens next to each parameter.
Stop 0x00 00 00 01
Terminates the server. Will need to be manually restarted. No parameters.
Echo 0x00 00 00 02
Echoes the payload back to the Webfront listen port. No parameters.
Client request state update 0x00 00 00 03
Triggers the server to package its global state and send it to the Webfront which can then display it for the client. No parameters.
STDEcho 0x00 00 00 04
Echoes the payload to the backend's standard out. No parameters.
SetValveState 0x00 00 00 05
Sets the global valve state. Parameters:
APIKey (64) Your application's API key (or the Webfront key).
valveState (4) The new state of the valves, represented as a 32-bit integer (see GlobalStateTracker.cpp in the enlight-backend project).
SetRestrictState 0x00 00 00 06
Sets the global valve restriction state. Parameters:
APIKey (64)
valveRestrictState (4) The new state of the valve restrictions, represented the same way as valveState from the SetValveState opcode.
ToggleValveState 0x00 00 00 07
Toggles the global valve state (indicated valves will switch their state). Parameters:
APIKey (64) Your application's API key (or the Webfront key).
valveState (4) The valves whose state to toggle, integer encoded.
TODO: The backend is also listening on insert port here for status updates from the cRIO itself (right?)
The Webfront sporadically listens on port 11911. It does this listening when it expects a global state update from the backend, which it should receive and use to update the global state. The Webfront uses this global state information and propagates it to the UI for display to the user. This global state is the latest information regarding the fountain as far as the Webfront is concerned, and it is refreshed every insert interval here by a client-side AJAX request to the Webfront to refresh the information. The Webfront then sends an update request to the server and starts listening on port 11911 for a global state update.
A state update datagram from the C++ server will consist of named "XML" fields with a value. For example:
<Variable1>Value1</><Variable2>Value2</>
These are all just strings and they can be parsed however the Webfront wants. They will be automatically parsed by the Webfront's fountainState object, which has accessor methods for the "latest received information" that can be used for state updates.