## xaajax
A generic HMI for xAAL devices able to handle dynamicity of xAAL
following everyone's approaches: web technologies, including ajax...


# Architecture
- lighttpd: the frontend
  . Serves static files (html, css, js, ...)
  . Manages one (or many) fastcgi process (start, monitor, kill, restart, ...)
  . Gives dynamic html requests to it
  . Optionnal: https hsts htaccess ...
- xaagent: the backend
  . Acts as the fascgi process for lighttpd, accepts dynamic html requests
  . Reply in json with information about what it learns about xAAL devices
  . Monitors the xAAL bus, store interesting information into an internal db

Note: The html and javascript parts are static files. The only dynamic part
are answers in the form of json data provided by the xaagent, handled by
ajax jqueries &co.  (Usable also as RESTful compliant gateway?  ;-) )


# Dependencies
- package of the lighttpd server itself
- the xAAL library
- packages: uuid-dev libjson-c-dev libfcgi-dev liburiparser-dev libsodium-dev


# Note
- Compares to xaagent v1, this v2 release replaces sqlite3 by simple linked lists.


# 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 xaagent.conf)
  (optional but recommended: have a schema repository, a metadata database,
   a cache)
- For a real use, edit lighttpd.conf to change port, verbosity level,
  configure htaccess, etc.


# How it works
- xaagent sends an isAlive request on the xAAL bus at startup.
- It listen 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.
  . Replies from metadatadb.any devices (addTagOnDevice, deleteDevice,
    getTagsWithDevice, deleteTag, deleteTagOnDevice, renameTag, renameDevice)
    It updates its DB (tags 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 tag information: xaagent sends a getTagsWithDevice 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 reight schema (following schmas that are extended by
    the schema of the device of the corresponding value)
- xaagent offers several threads to answers to fastcgi requests.
  The (RESTful) API is:
  . http://localhost:8888/json/devices[?tag=<name>]
      Returns an array of devices (just {address, devType, timeout}) having
      the given tag 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/tags?device=<uuid>
      Returns an array of known tags 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 is 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 mehod, 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
- 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 RESTfull API should not make any
  assumption on this.