README.TXT

# 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 metadata database, a cache)


## How it works
- xaaws sends an is_alive request on the xAAL bus at startup.

- It listens to alive notifications and store those devices in its DB.
  (Well, just the address; one has to wait to get a full description)
  It also stores the dev_type as an incomplete schema. (One just have the
  name; one has to query for a full specification later.)

- It listens to interesting xAAL replies.
  . get_attributes: 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.)
  . get_description: It updates the device in its DB with this info.
  . Messages from metadatadb.any devices (get_keys_values replies and
    keys_values_changed notifications).
    It updates its DB (map of keys-values on devices) according to this.
  . Replies from cache.any devices (get_device_attribute, get_device_attributes)
    It updates its DB (values of attributes of devices) according to this.

- Periodically, it looks at incomplete information in DB:
  . Schemas without a complete specification (one just known its name): try
    to download it from the documentation's uri of devices.
  . Devices without description (one just know the address): xaagent sends
    get_description requests to then.
  . Devices without metadata: xaagent sends a get_keys_values to known metadatadb
    about those devices.
  . Devices with attributes without a known value: sends a getAttribute request
    to those devices and a get_device_attribute 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, dev_type, 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?dev_type=<name>
      Returns an object with the specification of the requested dev_type.
      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:
      { "targets": [<array of device addresses (uuid)>],
	"action": "<string name of a method of those devices>",
	"body": {<object with parameters and values for the method>} }
  . http://localhost:8888/json/dump
      An Event Stream API to recieve a dump of xAAL messages
  . http://localhost:8888/json/attributes_change
      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 attributes_change from the xAAL bus
  . The "xaal-dump" WebSockets protocol:
	Sends: void
	Receive: get a dump of xAAL messages

- Comming soon: cbor REST/WebSockets API almost 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.