== ola

[[toc:]]

== Description

Basic bindings for libola, Open Lighting Architecture.  Classes covered so
far are DmxBuffer and StreamingClient.

For bug reports, feature requests, and development versions, visit the
[[https://github.com/retroj/ola-egg/|github project page]].

== Authors

* John J Foerch


== Requirements
=== Chicken Eggs

* [[r7rs]]
* [[srfi-99]]
* [[foreigners]]
* [[list-utils]]
* [[matchable]]

=== C Headers

* ola (libola-dev)


== API
=== Version

<procedure>(ola-version) => (major minor revision)</procedure>

Return ola's version as a list.

<procedure>(ola-version-string) => string</procedure>

Return ola's version as a string.

=== Logging

<procedure>(init-logging [level] [output]) => bool</procedure>

Level may be one of the following symbols:

* log-level/none
* log-level/fatal
* log-level/warn
* log-level/info
* log-level/debug
* log-level/max

Output may be one of the following symbols:

* log-output/stderr
* log-output/syslog
* log-output/null

=== DmxBuffer

<procedure>(dmxbuffer) => dmxbuffer</procedure>

Construct a new empty dmxbuffer.

<procedure>(dmxbuffer other-dmxbuffer) => dmxbuffer</procedure>

Construct a new dmxbuffer with the same contents as other-dmxbuffer.

<procedure>(dmxbuffer bytevector) => dmxbuffer</procedure>

Constructs a new dmxbuffer with the same contents as bytevector.

<procedure>(dmxbuffer? dmxbuffer) => bool</procedure>

Dmxbuffer predicate.

<procedure>(dmxbuffer=? dmxbuffer-a dmxbuffer-b) => bool</procedure>

Test whether dmxbuffer-a and dmxbuffer-b have equal contents.

<procedure>(dmxbuffer-size dmxbuffer) => size</procedure>

Size of dmxbuffer.

<procedure>(dmxbuffer-get dmxbuffer) => bytevector</procedure>

Return contents of dmxbuffer as a bytevector.

<procedure>(dmxbuffer-get-channel dmxbuffer channel) => value</procedure>

Return the value of the given channel in dmxbuffer.

<procedure>(dmxbuffer-get-range dmxbuffer offset length) => bytevector</procedure>

Return a bytevector of the requested range in dmxbuffer.

<procedure>(dmxbuffer-set! dmxbuffer bytevector offset size) => bool</procedure>

Set the contents of dmxbuffer to contents of bytevector at given offset and size.

<procedure>(dmxbuffer-set! dmxbuffer bytevector) => bool</procedure>

Set the contents of dmxbuffer to contents of bytevector.

<procedure>(dmxbuffer-set! dmxbuffer dmxbuffer-other) => bool</procedure>

Set the contents of dmxbuffer to contents of dmxbuffer-other.

<procedure>(dmxbuffer-set-channel! dmxbuffer channel value) => undefined</procedure>

Set dmxbuffer channel to value.

<procedure>(dmxbuffer-set-from-string! dmxbuffer str) => bool</procedure>

Complement of dmxbuffer->string.  Sets the contents of dmxbuffer according to the specially formatted string str.  The format of the string is integers separated by commas, where 0's may be omitted, e.g. "1,2,,255"

<procedure>(dmxbuffer-set-range! dmxbuffer dst-offset bytevector) => bool</procedure>

Set contents of dmxbuffer from dst-offset to contents of bytevector.

<procedure>(dmxbuffer-set-range! dmxbuffer dst-offset bytevector src-offset src-length) => bool</procedure>

Set contents of dmxbuffer from dst-offset to contents of bytevector, from src-offset, src-length bytes.

<procedure>(dmxbuffer-set-range-to-value! dmxbuffer offset value length) => bool</procedure>

Set contents of dmxbuffer from offset for length to value.

<procedure>(dmxbuffer-htp-merge! dmxbuffer other-dmxbuffer) => bool</procedure>

Perform an HTP merge (high value merge) with other-dmxbuffer into dmxbuffer.

<procedure>(dmxbuffer-blackout! dmxbuffer) => bool</procedure>

Set all channels to 0 in dmxbuffer.

<procedure>(dmxbuffer-reset! dmxbuffer) => undefined</procedure>

Reset dmxbuffer size to 0.

<procedure>(dmxbuffer->string dmxbuffer) => string</procedure>

Complement of 'dmxbuffer-set-from-string!'.  Returns a human-readable
string representing the contents of dmxbuffer - comma separated decimal
values.

=== StreamingClient

<procedure>(streamingclient [auto-start: bool] [server-port: port]) => streamingclient</procedure>

Constructs a client and attempts to establish a connection to the ola
daemon.  Auto-start is whether to start olad if it is not already running,
default true.  Server-port is the port to use, default 9010.  Signals an
'(exn ola)' condition if it fails to connect to the ola daemon.

<procedure>(streamingclient-stop streamingclient) => undefined</procedure>

Stops a streamingclient.

<procedure>(streamingclient-send-dmx streamingclient universe dmxbuffer) => bool</procedure>

Sends contents of dmxbuffer to the given universe on streamingclient.


== Examples

<enscript>
(use ola r7rs)
(let ((client (streamingclient auto-start: #f)))
  (streamingclient-send-dmx client 0 (dmxbuffer (string->utf8 "AeIoUaEiO"))))
</enscript>


== License

LGPL-3


== Version History

* 0.1 (2016-03-12) initial release
* 0.2 (2016-03-13) meta and documentation
* 0.3 (2016-03-13) streamingclient-setup removed, ola-version added
* 0.4 (2016-09-05) use bytevectors instead of blobs