PlaceOS::Driver

provide example settings for your driver that can be customised in backoffice

provide a description for your driver that will be diplayed in backoffice.

it supports rendering markdown, so you can provide links to manuals and photos etc

This is the name of the device you are writing a driver for.

examples such as: Sony VISCA Camera, Samsung MDC Protocol

This is the name other drivers and frontends will use to access the driver functionality

exmaples such as: Camera, Display

when using a TCP protocol, we want to close the connection after every request / response

Change the log level at run-time. Toggle TRACE level logging using kill -s USR1 %PID

returns the current value of a status value and raises if it does not exist

Expose a status key to other drivers and frontends #} allowing them to bind to value updates

returns the current value of a status value and nil if it does not exist

the modules database configuration

if you would like to save an updated value to settings so it survives restarts

forces a disconnect of the network transport, which will promptly reconnect

was the current function executed directly by a user?

the id of the currently running module

monitor for messages being published on redis

subscription = monitor("my_service/channel") { |subscription, string_value| ... }

use subscriptions.unsubscribe(subscription) to unsubscribe

publishes a message to a channel on redis, available to any drivers monitoring for these events

publish("my_service/channel", "payload contents")

Queue a task that intends to use the transport layer

primarily useful where a device can only perform a single function at a time and ordering is important

i.e power-on, switch-input, set-volume

however you typically won't need to use this function directly. See #send

opts options include:

• priority: an Int between 0 and 100 where 0 is highest priority and 100 is the lowest

• timeout: a Time::Span indicating the maximum time the task should wait for a response

• retries: how many attempts should be made to successfully complete a task

• wait: Bool should we wait for a response (defaults to true)

• name: String of the command, if there is already a command with the same name in the queue, it will be replaced with this.

• delay: Time::Span how long to wait after executing this command before executing the next

• clear_queue: Bool after executing task, clear all the remaining tasks in the queue

queues a message to be sent to the transport layer.

see #queue for available options

queues a message to be sent to the transport layer.

the provided block is used to process responses while this task is active

used to provide feedback in backoffice about the state of a driver

online: true == Green, online: false == Red in backoffice

setting status_only: false will set the queue online state.

when offline, this means the queue will ignore all unnamed tasks to avoid memory leaks.

pushes a change notification for the key specified, even though it hasn't changed

Subscribe to a local status value

subscription = subscribe(:my_status) { |subscription, string_value| ... }

use subscriptions.unsubscribe(subscription) to unsubscribe

provides access to the modules subscriptions tracker

provides access to the details of a remote system, if you have the ID of the system.

provides access to the details of the system the logic driver is running in.

NOTE:: this only works for logic drivers as other drivers can be in multiple systems.

sends a wake-on-lan message the specified mac_address, specify a subnet for directed WOL

Creates helper methods in logic drivers for accessing other drivers in a system

For example, if you want to access system[:Display_1] via display use accessor display : Display_1

for system.all(Camera) use accessor cameras : Array(Camera)

for system.all(Display, implementing: Interface::Powerable) use accessor displays : Array(Display), implementing: Interface::Powerable

for system.implementing(Interface::Powerable) use accessor powerable, implementing: Interface::Powerable

a helper for any driver to bind to changes in its own status values logic drivers can additionally bind to status values on remote drivers

local bind: bind :power, :power_changed

remote bind: bind Display_1, :power, :power_changed

the new_value provided in the handler is a JSON string

you would define your handler as protected def power_changed(_subscription, new_value : String)

compile every transport into the binary, regardless of the discovery settings defined. Used by specs and documentation builds, the same can be achieved with the -Dplaceos_all_transports compiler flag

provides a generic method for handling otherwise unhandled errors in your drivers functions i.e. rescue_from(DivisionByZeroError, :return_zero) or alternatively: rescue_from(DivisionByZeroError) { 0 }

reads the provided class type out of the settings provided at the provided key.

i.e. given a setting: values: [1, 2, 3]

you can extract index 2 number using: setting(Int64, :values, 2)

reads the provided class type out of the settings provided at the provided key.

i.e. given a setting: keys: {"public": "123456"}

you can extract the public key using: setting?(String, :keys, :public)

reads a status key and deserialises the value into the class provided.

It raises if the class does not exist.

reads a status key and deserialises the value into the class provided.

It returns nil if the key doesn't exist

define a TCP port default if your driver connects over a raw TCP socket

this compiles the TCP and SSH transports into the driver

define a UDP port default if your driver connects over a raw UDP socket

also use this if you are using multicast for communications

this compiles the UDP transport into the driver

the default base URI for a service driver, all HTTP requests will have this domain and path appended

for example: https://api.google.com/

this compiles the HTTP and websocket transports into the driver