# xaaws - xAAL with WebSockets
A generic HMI for xAAL devices able to handle dynamicity of xAAL
following everyone's approaches: web technologies, including ajax
and web sockets...
## Architecture
- A core sever based on libwebosckets
with 3 "protocols": http-only, xaal, xaal-dump
And an agent which monitors the xAAL bus, store interesting information
into an internal ad-hoc db
- The "http-only" protocol
. Serves static files (html, css, js, ...)
. Implements a json REST API (see bellow) to give information about what
was learned about xAAL devices
. Implements a POST API to pass requests to the xAAL bus
Note: The html and javascript parts are static files. The only dynamic part
are answers in the form of json data provided REST and WebSockets API.
## Dependencies
- the libwebosckets library (2.0.3)
- the xAAL library
- packages: uuid-dev libjson-c-dev libfcgi-dev liburiparser-dev
libsodium-dev libwebsockets-dev
## To Test It
- Type `make test`
- Go to `http://localhost:8888/` with your favorite web browser (with javascript)
- Have some xAAL devices on the xAAL bus 224.0.29.200:1234 (see xaaws.conf)
(optional but recommended: have a schema repository, a metadata database,
a cache)
## How it works
- xaaws sends an isAlive request on the xAAL bus at startup.
- It listens to alive notifications and store those devices on its DB.
(Well, just the address; one has to wait to get a full description)
It also stores the devType as an incomplete schema. (One just have the
name; one has to wait to get a full specification.)
- It listens to interesting xAAL replies (not requests! guess why)
. getAttributes: It stores those values of attributes on its DB, and try to
link this to known schemas. (Issue: the corresponding schema may not be
fully present in DB at this time, nor the schema it extends... Therefore,
one has to wait to link the value to the right attribute of the right
schema.)
. getDescription: It updates the device in its DB with this info.
. Messages from metadatadb.any devices (getKeysValues replies and
keysValuesChanged notifications).
It updates its DB (map of keys-values on devices) according to this.
. Replies from cache.any devices (getDeviceAttribute, getDeviceAttributes)
It updates its DB (values of attributes of devices) according to this.
. Replies from schemarepository.any devices (getSchema)
It update its DB (specification of schema) according to this.
- Periodically, it looks at incomplete information in DB:
. Devices without description (one just know the address): xaagent sends
getDescription requests to then.
. Devices without metadata: xaagent sends a getKeysValues to known metadatadb
about those devices.
. Schemas without a complete specification (one just known its name): xaagent
sends getSchema requests to known schemarepository devices.
. Devices with attributes without a known value: sends a getAttribute request
to those devices and a getDeviceAttribute request to known caches.
. Devices having reached theire timeout (plus a grace delay): remove them.
. Check values linked to an ad-hoc attribute and try to re-link them to the
right attribute of the right schema (following sechmas that are extended by
the schema of the device of the corresponding value)
- The REST API:
. http://localhost:8888/json/devices[?key=]
Returns an array of devices (just {address, devType, timeout}) having
the given metadata key if provided, or all devices.
. http://localhost:8888/json/description?device=
Returns an object with the known description of the requested device.
. http://localhost:8888/json/attributes?device=
Returns an array of known values of attributes of the requested device.
. http://localhost:8888/json/methods?device=
Returns an array of known methods of the requested device including
those of inherited schemas.
. http://localhost:8888/json/map?device=
Returns the map of metadata keys-values of the requested device.
. http://localhost:8888/json/schema?devType=
Returns an object with the specification of the requested devType.
Note that lists of attributes methods and notifications include those of
schemas that are extended by the requested one (if they are known).
. http://localhost:8888/json/send
A POST request. The content should be a json object having:
{ "header": { "targets": []
"action": },
"body": }
. http://localhost:8888/json/dump
An Event Stream API to recieve a dump of xAAL messages
. http://localhost:8888/json/attributesChange
An Event Stream API to get informed of attributes change
- The WebSockets API:
. The "xaal-ctl" WebSockets protocol:
Sends: pass requests to the xAAL bus like the POST API
Receive: get attributesChange from the xAAL bus
. The "xaal-dump" WebSockets protocol:
Sends: void
Receive: get a dump of xAAL messages
- Disclamer: Returned information may be partial. Since xAAL is a distributed
system, there can't be any warranty about the completeness of the knowledge
of the global system state. Clients of this REST/WS API should not make any
assumption on this.