|
Deprecated
|
MessageFlow
Message Flow in Media System Software
Table Of Contents
The PiBox Development Platform is an open platform which means it doesn't not imply or implement rules of development. It is, in essence, a base Linux platform. The PiBox Media Systems, server and player, are somewhat different. They provide a UI with app infrastructure that requires a mechanism of passing data between components. While a number of message passing software libraries are available, there is no reason to add that overhead to an environment a simplified as PiBox. Instead, a simple protocol is used over sockets. Currently TCP sockets are used on the local host and the only API available - piboxMsg() in libpibox - is for sending messages from a client to piboxd. However, more API support is planned for future use in app development. This will make it possible to switch message transports without affecting app developers.
Figure 1 shows the set of apps and daemons that run in a media server or player and the message paths between them. The apps and daemons can be divided into three component sets: UI, services and external. The UI includes the appmgr, launcher and apps that provide end-user functionality such as the video player. The launcher provides the user interface on the console. It sends messages to the appmgr which responsible for managing which apps are running in the UI. The services component includes the piboxd daemon and the Web UI. The piboxd daemon provides privileged access to underlying OS services. The Web UI and apps communicate with the piboxd to proxy actions they can't take on their own. The Web UI provides a web based user interface that includes access to the web cam (if one is connected). External apps run on Android and communicate directly with the RESTful interface in the Web UI which may proxy requests to other daemons as necessary.
Packet Format
PiBox uses a very simplistic packet protocol. A 4-byte header holds an 8 bit type fields with possible actions and subactions (the other 8 bits are for future expansion). Subactions are associated with specific actions and actions are associated with specific types. Types are context defined. More on these later. Following the header is a 32bit payload size field. This is the length of the payload that follows. A payload is not required so this field can be zero. The tag and filename fields are only used in some contexts, specifically with requests for web cam video. The tag is a 36 character UUID using the printf format %08x-%04x-%04x-%04x-%012x. The filename is always "webcam" to request the webcam be started. Other contexts ignore these as separate fields and simply use them as the payload field. The payload is a byte-field that is payload-size length. Packet handlers read in this much data or time out waiting for the data. Once the packet is read it is stuffed into an appropriate data structure and passed to the type and action handlers. Responses
If a message requires a response it uses a simple length/payload message format. The sender of the response sends a four-byte length followed by a payload. The receiver of the response reads the length first and then the payload. The following sections need to be cleaned up. This is not the complete API. See pmsg.h in libpibox for the complete API. Launcher->appmgr
appmgr->apps
apps->piboxd
Apps can request and set IoT device configurations. This is how, for example, an app can manage a thermostat, vents or window blinds. Data returned from the piboxd server is in JSON format. Data sent to the piboxd server as a payload must be in JSON format. The json format in the server looks like this:
{
"ip-address": {
"identity": "uuid",
"features": {
"name": "set",
"name-display": "Vent Damper",
"name-set": "0,25,50,75,100"
"name-value": "50"
},
"lastContact": 1457751835
}
}
When an app requests a device by IP this is what it gets back. When it sends an updated configuration, such as when it requests the damper to be open to 100%, the request looks like this:
ip-address
{
"identity": "uuid",
"features": {
"name": "set",
"name-display": "Vent Damper",
"name-set": "0,25,50,75,100"
"name-value": "50"
},
}
In this case the IP address comes before the JSON context and the lastContact field can be left off. All other fields must be present, however, as this new object will replace the old one. The IP address must have all colons (:) replaced with a dash (-) when sending from app to server. The server always responds with the same format. The name is a feature name (aka a field to set in the UI) and defines the type of data it accepts. The name-display is the name to use in the UI for that feature. The data types are set, num, text, or range. A name-<type> can be used to define the default values to display, such as in a drop down or scrolled list. The name-value is the current value of the field. This is usually the only value sent back from the UI to the piboxd in the features object as it is the new setting to apply.
web UI, app<->piboxd
Android->web UI
|
