File "src/xpl/classes/xpldevice.lua"

The base object for xPL devices. It features all the main characteristics of the xPL devices, so only user code needs to be added. Starting, stopping, regular heartbeats, configuration has all been implemented in this base class.
 
No global will be created, it just returns the xpldevice base class. The main xPL module will create a global xpl.classes.xpldevice to access it.
 
You can create a new device from; xpl.classes.xpldevice:new( {} ), but it is probably best to use the new_device_template.lua file as an example on how to use the xpldevice class

Copyright © 2011 Thijs Schreijer

Release: Version 0.1, LuaxPL framework.

Tables

xpldevice fields/properties Members of the xpldevice object

Functions

xpldevice:createhbeatmsg (exit) Heartbeat message creator.
xpldevice:eventhandler (sender, event, param, ...) Handles incoming events.
xpldevice:getsettings () Gets a table with the device settings to persist.
xpldevice:handlemessage (msg) Handler for incoming messages.
xpldevice:initialize () Initializes the xpldevice.
xpldevice:restart () Restarts the xpldevice (only if already started, remains stopped otherwise).
xpldevice:send (msg) Sends xpl message.
xpldevice:sendhbeat (exit) Sends heartbeat message.
xpldevice:setsettings (s) Sets the provided settings in the device.
xpldevice:start () Starts the xpldevice.
xpldevice:statuschanged (newstatus, oldstatus) Handler called whenever the device status (either "online", "connecting" or "offline") changes.
xpldevice:stop () Stops the xpldevice.


Tables

xpldevice fields/properties
Members of the xpldevice object

Fields

  • address: (string) the xpladdress of the device
  • interval: (number) the xpl heartbeat interval in minutes
  • status: (string) current status of the connection for this device; "online", "connecting", "offline"
  • filter: either nil or the xplfilters object with the filter list for the device
  • classname: (string) the name of this class, basically the filename without the extension. Required to identify the type of class, but also to re-create a device from persistence.
  • configitems: table to hold the current config items, will start with the regular xPL config items; newconf, interval, filters, groups
  • configurable: (boolean) if false the device will not respond to configuration messages
  • configured: (boolean) true if the device has been configured
  • version: (string) a version number to report in the hearbeat messages, set to nil to not report a version

Functions

xpldevice:createhbeatmsg (exit)
Heartbeat message creator. Will be called to create the heartbeat message to be send. Override this function to modify the hbeat content.

Parameters:

  • exit: if true then an exit hbeat message, (hbeat.end or config.end) needs to be created.

Return value:

xplmessage object with the heartbeat message to be sent.
xpldevice:eventhandler (sender, event, param, ...)
Handles incoming events. Will deal with copas starting/stopping and listener messages. See CopasTimer documentation on how to use the events.

Parameters:

  • sender: the originator of the event
  • event: the event string
  • param: first event parameter, in case of an xpllistener event newmessage this will for example be the xplmessage received.
  • ...: any additional event parameters
xpldevice:getsettings ()
Gets a table with the device settings to persist. Override this function to add additional settings. All xpl config items in the configitems table will be included automatically by the base class.

Return value:

table with settings
xpldevice:handlemessage (msg)
Handler for incoming messages. It will handle the heartbeat messages (echos) to verify the devices own connection and heartbeat requests. If the device is configurable it will also deal with the configuration messages.
 Override this method to handle incoming messages, see the new_device_template.lua for an example.

Parameters:

Return value:

the xplmessage object received, or nil if it was handled (eg hbeat, our own echo, etc.)
xpldevice:initialize ()
Initializes the xpldevice. Will be called upon instantiation of an object, override this method to set default values for all properties. It will also subscribe to copas and xpl.listener events for starting, stopping and new message events. Use setsettings() to restore settings from persistence.
xpldevice:restart ()
Restarts the xpldevice (only if already started, remains stopped otherwise). Use this method after configuration changes that require a device restart.
xpldevice:send (msg)
Sends xpl message. Will send either a string or an xplmessage object. In the latter case it will set the source property to the address of the device sending.

Parameters:

  • msg: message to send
xpldevice:sendhbeat (exit)
Sends heartbeat message. Will send a heartbeat message, the message will be collected from the createhbeatmsg() function.

Parameters:

  • exit: if true then an exit hbeat message (hbeat.end or config.end) will be send.
xpldevice:setsettings (s)
Sets the provided settings in the device. Override this method to add additional settings

Parameters:

  • s: table with settings as generated by getsettings().

Usage:

if mydev:setsettings(mysettings) then mydev:restart() end

Return value:

true if the settings provided require a restart of the device (when the instance name changed for example). Make sure to call restart() in that case.
xpldevice:start ()
Starts the xpldevice. Will run on the copas start event.
xpldevice:statuschanged (newstatus, oldstatus)
Handler called whenever the device status (either "online", "connecting" or "offline") changes. Override this method to implement code upon status changes.

Parameters:

  • newstatus: the new status of the device
  • oldstatus: the previous status
xpldevice:stop ()
Stops the xpldevice. Will run on the copas stop event.

Valid XHTML 1.0!