62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
# Library for E1.31 sACN
|
|
## `Lightweight streaming protocol for transport of DMX512 using ACN`
|
|
|
|
## Top level include
|
|
|
|
Include `sacn.h` for full protocol support.
|
|
|
|
> ```#include "sacn.h"```
|
|
|
|
### Requirements
|
|
Expects to also have the `acn` and `dmx` libraries in the include path.
|
|
|
|
## Logical components
|
|
|
|
### Protocol Handling
|
|
* `sacn.h`: [`SACN`] protocol constants.
|
|
* `data.h`: [`SACN::DATA`] protocol support for `VECTOR_ROOT_E131_DATA` packets.
|
|
* `extended.h`: [`SACN::EXTENDED`] protocol support for `VECTOR_ROOT_E131_EXTENDED` packets
|
|
|
|
### Data Classes
|
|
* `universe.h`: [`SACN::Universe`] A set of up to 512 data slots identified by universe number. Note: In E1.31 there may be multiple sources for a universe.
|
|
> For protocol agnostic universe refer to the base class, `DMX::Universe`
|
|
|
|
* `receiver.h`: [`SACN::Receiver`] A receiver is the intended target of information from a source. A receiver may listen for multiple universes.
|
|
|
|
* `source.h`: [`SACN::Source`] A sACN component that assembles, formats, and transmits data to one or many receivers.
|
|
|
|
* `node.h`: [`SACN::Node`] A class that inherits from both `SACN::Source` and `SACN::Receiver`. IE. can both send and receive. The node class also manages universe discovery.
|
|
|
|
### Reference Implementations
|
|
|
|
Several reference implementations may be available in the `platform` subdirectory.
|
|
|
|
* `receiver-esp.h`: [`SACN::EspReceiver`] A reference implementation, derived from `SACN::Receiver` for use with ESP devices and Arduino.
|
|
|
|
* `qsacnnode.h`: [`SACN::QSacnNode`] An implementation that inherits from `SACN::Node`, which handles all of the mucky hardware and network with Qt.
|
|
|
|
## Usage with Arduino
|
|
|
|
Include `receiver-esp.h` at the top of your sketch.
|
|
|
|
Create a receiver object.
|
|
> ```
|
|
> EspReceiver * e131 = new EspReceiver();
|
|
> ```
|
|
|
|
In `setup`, subscribe to a universe an register a callback for data activity.
|
|
> ```
|
|
setup() {
|
|
e131->subscribe(1);
|
|
e131->universe(1)->onData(std::bind(&universeHandler,
|
|
std::placeholders::_1));
|
|
}
|
|
>```
|
|
|
|
Write a handler function with the follow signature (returns `void`, requires 1 argument, a `Universe` pointer):
|
|
> ```
|
|
void universeHandler(Universe * universe) {
|
|
do something...
|
|
}
|
|
> ```
|