# 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 <https://libwebsockets.org/>
  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 json REST API:
  . http://localhost:8888/json/devices[?key=<name>]
      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=<uuid>
      Returns an object with the known description of the requested device.
  . http://localhost:8888/json/attributes?device=<uuid>
      Returns an array of known values of attributes of the requested device.
  . http://localhost:8888/json/methods?device=<uuid>
      Returns an array of known methods of the requested device including
      those of inherited schemas.
  . http://localhost:8888/json/map?device=<uuid>
      Returns the map of metadata keys-values of the requested device.
  . http://localhost:8888/json/schema?devType=<name>
      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": [<array of device addresses (uuid)>]
		    "action": <name of the method to those devices> },
	"body": <parameters and values for the method, if needed> }
  . 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 json 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

- Comming soon: cbor REST/WebSockets API similar to json ones

- 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.