Module "xpl"

This module contains the main xPL functionality. Upon requiring it, it will load all supporting modules and classes. To use the framework you should only need to require("xpl") and any of your own devices (see the included device template for a quick start).
 
A global xpl will be created. Through this global the following components are accessible;


The xPL framework uses 'CopasTimer' to provide timers, events and backgroundworkers. Please consult the 'CopasTimer' documentation on how this works.

Copyright © 2011 Thijs Schreijer

Release: Version 0.1, LuaxPL framework.

Tables

const contains constants for the xPL module
settings contains the general settings for the xPL module

Functions

xpl.createaddress (vendor, device, instance) Creates an xPL address.
xpl.send (msg, ip, port) Sends an xPL message
xpl.start (...) Starts the loop and from there the listener, hub and devices.
xpl.stop (...) Exits the loop and from there stops the listener, hub and devices.


Tables

const
contains constants for the xPL module

Fields

  • CAP_ADDRESS: pattern to return the three elements of an address, no wildcards allowed
  • CAP_FILTER: pattern to return the 6 elements of an xPL filter, wildcards are allowed, and the '-' instead of a '.' between vendor and device is also supported (special case)
  • CAP_MESSAGE: pattern that returns the header information, body (as one string) and the remaining string (the remaining string can be used for the next iteration)
  • CAP_KEYVALUE: pattern that captures a key-value pair (must end with \n), and the remaining string (the remaining string can be used for the next iteration)
  • CAP_SCHEMA: pattern that captures a schema class and type from a full schema
  • FMT_KEYVALUE: format string for creating the message body; existing body, key, value
  • FMT_MESSAGE: format string for creating messages; type, hop, source, target, schema, body (hop is number, others string)
settings
contains the general settings for the xPL module

Fields

  • _DEBUG: (boolean) set the debug flag and executes available tests at startup
  • listenon: unused for now
  • listento: ANY_LOCAL (peers within same subnet) or table with IP addresses (applies only to hub function)
  • broadcast: the IP address to use for broadcasting xPL messages onto the xPL network
  • xplport: the xPL network port, do not change! only if you want to create a private network and know what you are doing
  • xplhub: (boolean) should the internal hub be started
  • netcheckinterval: (number) interval in seconds for checking the network connection for any changes (defaults to 30).
  • devices: (table) table with device specific settings, key is device table, value is device specific settings. Fixed fields in the settings table are;
    • classname (string) name of the class to create the device
    • updatehandler (function) may be called from the device when its settings have changed
    • ...
    • ...

Functions

xpl.createaddress (vendor, device, instance)
Creates an xPL address.

Parameters:

  • vendor: (string) the vendor id to use in the address
  • device: (string) the device id to use in the address
  • instance: (string) the instance id to use in the address, with 2 special cases;
    • 'HOST' will generated an instance id based upon the system hostname
    • 'RANDOM' will generate a random instance id

Return value:

xPL address string, formatted as 'vendor-device.instance'
xpl.send (msg, ip, port)
Sends an xPL message

Parameters:

  • msg: (string) message to be sent.
  • ip: (string) optional, do not use, only for internal use by the hub
  • port: (number) optional, do not use, only for internal use by the hub

Return value:

true if succesfull, nil and error otherwise
xpl.start (...)
Starts the loop and from there the listener, hub and devices. This is a simple shortcut to copas.loop() and it takes the same parameters

Parameters:

  • ...:
xpl.stop (...)
Exits the loop and from there stops the listener, hub and devices. This is a simple shortcut to copas.exitloop() and it takes the same parameters

Parameters:

  • ...:

Valid XHTML 1.0!