tinylor.h File Reference

A tiny library for generating LOR protocol requests. More...

#include <stddef.h>

Include dependency graph for tinylor.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	lor_channel_set
	Represents a grouping of 16 channels, as a bit set, aligned to a 16-channel boundary (via a multiplier). More...
union	lor_effect_data
	Union of effect argument structures that may be required by assorted effect types: LOR_SET_LIGHTS, LOR_FADE, LOR_PULSE, and LOR_SET_DMX_INTENSITY. More...
struct	lor_req
	Represents a request to apply an effect to a set of channels on a specific unit. The effect may require additional arguments, which are stored in the args field. Fields may be set directly, or better yet, by using the provided helper functions which handle potential data validation/conversion that you may not want to do. More...

Macros
#define	LOR_HEARTBEAT_BYTES   ((unsigned char[]){0, 0xFF, 0x81, 0x56, 0})
	The pre-defined binary representation of a LOR heartbeat message.
#define	LOR_HEARTBEAT_SIZE   5
	The length of the LOR heartbeat message LOR_HEARTBEAT_BYTES.
#define	LOR_HEARTBEAT_DELAY_MS   500
	The intended delay in milliseconds between sending LOR heartbeats.
#define	LOR_HEARTBEAT_DELAY_NS   500000000
	The intended delay in nanoseconds between sending LOR heartbeats.

Typedefs
typedef unsigned short	lor_channel
	Represents a channel number, which is a unique identifier for a specific light or group of lights. Channels are typically in the range of [1, 1024].
typedef unsigned char	lor_intensity
	Represents a scaled intensity value used by the LOR protocol.
typedef unsigned char	lor_unit
	Represents a unit number, which is a unique identifier for a piece of LOR hardware. A value of 0xFF is reserved for broadcast messages. Units are typically in the range of [1, 0xF1] (1-241).
typedef unsigned short	lor_decisec
	Represents a duration in deciseconds, which is 1/10th of a second.
typedef struct lor_channel_set	lor_channel_set
typedef enum lor_effect	lor_effect
typedef enum lor_channel_format	lor_channel_format
typedef union lor_effect_data	lor_effect_args_u
typedef struct lor_req	lor_req_s
typedef lor_intensity(*	lor_intensity_fn) (unsigned char b)
	Represents a function that converts an arbitrary byte value to a a scaled intensity value used by the LOR protocol.

Enumerations
enum	lor_effect {   LOR_SET_LIGHTS = 0x01 , LOR_SET_OFF = 0x02 , LOR_SET_INTENSITY = 0x03 , LOR_FADE = 0x04 ,   LOR_PULSE = 0x05 , LOR_TWINKLE = 0x06 , LOR_SHIMMER = 0x07 , LOR_SET_DMX_INTENSITY = 0x08 }
	Represents the various effects that may be applied to a set of channels on a specific unit. Each effect may require additional arguments, which are stored in the args field of the lor_req_s structure. Fields may be set directly, or better yet, by using the provided helper functions which handle potential data validation and conversion that you may not want to do. More...
enum	lor_channel_format {   LOR_FMT_SINGLE = 0x00 , LOR_FMT_16 = 0x10 , LOR_FMT_8L = 0x20 , LOR_FMT_8H = 0x30 ,   LOR_FMT_UNIT = 0x40 , LOR_FMT_MULTIPART = 0x50 }
	Represents the various formats that a channel set may be encoded in for the LOR protocol. The format is used to determine how the channel set is encoded into binary data for transmission. The format is determined by the number of channels in the set and the alignment of the first channel in the set. More...

Functions
void	lor_set_channel (lor_req_s *req, lor_channel c)
	Configures the request to use a single, absolute channel.
void	lor_set_channels (lor_req_s *req, lor_channel first, unsigned short cbits)
	Configures the request to use a channel set, in the form of a 16-bit bitset of channels, "starting at" the first channel offset used.
void	lor_set_unit (lor_req_s *req, lor_unit u)
	Configures the request to be sent to the specified unit. A unit is required for all requests. A magic value of 0xFF may be used to broadcast the request to all units.
int	lor_set_effect (lor_req_s *req, lor_effect e, const lor_effect_args_u *args)
	Configures the request to apply the specified effect. The effect may require additional arguments, which are provided in the args field as a union. If provided, the args field is copied into the request at which point the caller may safely discard the original args. Any non-NULL arguments will be copied into the request, even if the effect does not require them. This allows future expansion of usable effects without modifying the behavior of the function.
void	lor_set_intensity (lor_req_s *req, lor_intensity i)
	Configures the request to set the intensity of the lights to the provided value.
void	lor_set_fade (lor_req_s *req, lor_intensity start, lor_intensity end, lor_decisec ds)
	Configures the request to fade from one intensity to another over a specified duration in deciseconds.
size_t	lor_write (unsigned char *b, size_t bs, const lor_req_s *r, size_t rs)
	Encodes and writes up to rs requests to the provided buffer b as binary data. Requests are first encoded into a scratch buffer to ensure the buffer has enough space to hold the encoded data. The function will attempt to write as many requests as possible to the buffer, up to the provided request count.
lor_intensity	lor_get_intensity (unsigned char b)
	Encodes a [0,0xFF] value into a roughly equivalent LOR intensity value (precision is lossy) that is compatible with the protocol.

Detailed Description

A tiny library for generating LOR protocol requests.

Macro Definition Documentation

LOR_HEARTBEAT_BYTES

#define LOR_HEARTBEAT_BYTES   ((unsigned char[]){0, 0xFF, 0x81, 0x56, 0})

The pre-defined binary representation of a LOR heartbeat message.

LOR_HEARTBEAT_DELAY_MS

#define LOR_HEARTBEAT_DELAY_MS   500

The intended delay in milliseconds between sending LOR heartbeats.

LOR_HEARTBEAT_DELAY_NS

#define LOR_HEARTBEAT_DELAY_NS   500000000

The intended delay in nanoseconds between sending LOR heartbeats.

LOR_HEARTBEAT_SIZE

#define LOR_HEARTBEAT_SIZE   5

The length of the LOR heartbeat message LOR_HEARTBEAT_BYTES.

Typedef Documentation

lor_channel

lor_channel

Represents a channel number, which is a unique identifier for a specific light or group of lights. Channels are typically in the range of [1, 1024].

lor_channel_format

typedef enum lor_channel_format lor_channel_format

lor_channel_set

typedef struct lor_channel_set lor_channel_set

lor_decisec

lor_decisec

Represents a duration in deciseconds, which is 1/10th of a second.

lor_effect

typedef enum lor_effect lor_effect

lor_effect_args_u

typedef union lor_effect_data lor_effect_args_u

lor_intensity

lor_intensity

Represents a scaled intensity value used by the LOR protocol.

Note

The value must be first converted to a scaled intensity value before being passed to the LOR protocol.

lor_intensity_fn

lor_intensity_fn

Represents a function that converts an arbitrary byte value to a a scaled intensity value used by the LOR protocol.

lor_req_s

typedef struct lor_req lor_req_s

lor_unit

lor_unit

Represents a unit number, which is a unique identifier for a piece of LOR hardware. A value of 0xFF is reserved for broadcast messages. Units are typically in the range of [1, 0xF1] (1-241).

Enumeration Type Documentation

lor_channel_format

enum lor_channel_format

Represents the various formats that a channel set may be encoded in for the LOR protocol. The format is used to determine how the channel set is encoded into binary data for transmission. The format is determined by the number of channels in the set and the alignment of the first channel in the set.

Enumerator
LOR_FMT_SINGLE	Single channel.
LOR_FMT_16	16-bit bitset of channels.
LOR_FMT_8L	8-bit bitset of channels, low byte.
LOR_FMT_8H	8-bit bitset of channels, high byte.
LOR_FMT_UNIT	Unit number, no channels.
LOR_FMT_MULTIPART	Multi-part channel set.

lor_effect

enum lor_effect

Represents the various effects that may be applied to a set of channels on a specific unit. Each effect may require additional arguments, which are stored in the args field of the lor_req_s structure. Fields may be set directly, or better yet, by using the provided helper functions which handle potential data validation and conversion that you may not want to do.

Enumerator
LOR_SET_LIGHTS	Set the lights to full intensity.
LOR_SET_OFF	Turn the lights off.
LOR_SET_INTENSITY	Set the lights to a specific intensity.
LOR_FADE	Fade between two intensities over time.
LOR_PULSE	Cycle the lights between two intensities.
LOR_TWINKLE	Twinkle the lights using hardware controls.
LOR_SHIMMER	Shimmer the lights using hardware controls.
LOR_SET_DMX_INTENSITY	Write raw DMX protocol data.

Function Documentation

lor_get_intensity()

lor_intensity lor_get_intensity

(

unsigned char

b

)

Encodes a [0,0xFF] value into a roughly equivalent LOR intensity value (precision is lossy) that is compatible with the protocol.

Note

This is a default implementation of the lor_intensity_fn type. It operates via a known truth table from protocol documentation. Other or custom implementations may be ideal for your specific use case.

Parameters

b	The byte value to convert.

Returns

The scaled intensity value.

lor_set_channel()

void lor_set_channel	(	lor_req_s *	req,
		lor_channel	c
	)

Configures the request to use a single, absolute channel.

Parameters

req	The request to configure.
c	The single, absolute channel to apply the effect to, less than 1024.

lor_set_channels()

void lor_set_channels	(	lor_req_s *	req,
		lor_channel	first,
		unsigned short	cbits
	)

Configures the request to use a channel set, in the form of a 16-bit bitset of channels, "starting at" the first channel offset used.

Note

Any bits within the set that (once re-aligned to a 16-bit boundary) exceed the 16-bit window, will be disregarded. Pre-aligned 16-bit bitsets are recommended for best results. You may set the request's cset offset and cbits fields directly.

Parameters

req	The request to configure.
first	The first channel in the set.
cbits	The 16-bit bitset of channels to apply the effect to.

Here is the caller graph for this function:

lor_set_effect()

int lor_set_effect	(	lor_req_s *	req,
		lor_effect	e,
		const lor_effect_args_u *	args
	)

Configures the request to apply the specified effect. The effect may require additional arguments, which are provided in the args field as a union. If provided, the args field is copied into the request at which point the caller may safely discard the original args. Any non-NULL arguments will be copied into the request, even if the effect does not require them. This allows future expansion of usable effects without modifying the behavior of the function.

Parameters

req	The request to configure.
e	The effect to apply.
args	The effect arguments, required if effect is LOR_SET_INTENSITY, LOR_FADE, LOR_PULSE, or LOR_SET_DMX_INTENSITY. Should likely be NULL for other effect types.

Returns

0 on success, -1 for invalid arguments.

Here is the caller graph for this function:

lor_set_fade()

void lor_set_fade	(	lor_req_s *	req,
		lor_intensity	start,
		lor_intensity	end,
		lor_decisec	ds
	)

Configures the request to fade from one intensity to another over a specified duration in deciseconds.

Note

Equivalent to calling lor_set_effect with LOR_FADE and effect arguments set to the provided start and end intensities and duration.

Parameters

req	The request to configure.
start	The starting intensity.
end	The ending intensity.
ds	The duration of the fade in deciseconds.

Here is the call graph for this function:

lor_set_intensity()

void lor_set_intensity	(	lor_req_s *	req,
		lor_intensity	i
	)

Configures the request to set the intensity of the lights to the provided value.

Note

Equivalent to calling lor_set_effect with LOR_SET_INTENSITY and effect arguments set to the provided intensity.

Parameters

req	The request to configure.
i	The intensity to use. This value should likely pass through a intensity conversion function before being passed to this function.

Here is the call graph for this function:

lor_set_unit()

void lor_set_unit	(	lor_req_s *	req,
		lor_unit	u
	)

Configures the request to be sent to the specified unit. A unit is required for all requests. A magic value of 0xFF may be used to broadcast the request to all units.

Parameters

req	The request to configure.
u	The unit to send the request to, or 0xFF to broadcast to all units.

Here is the caller graph for this function:

lor_write()

size_t lor_write	(	unsigned char *	b,
		size_t	bs,
		const lor_req_s *	r,
		size_t	rs
	)

Encodes and writes up to rs requests to the provided buffer b as binary data. Requests are first encoded into a scratch buffer to ensure the buffer has enough space to hold the encoded data. The function will attempt to write as many requests as possible to the buffer, up to the provided request count.

Returns

If all requests were written, the number of bytes written to the buffer is returned. If the buffer is too small to hold all requests, the number of bytes required to hold at least one additional request is returned.

Here is the call graph for this function:

Here is the caller graph for this function: