Handler¶

A handler provides one or more callable functions. Before the functions are accessible over the remote procedure call interface the handler must be connected to the system. A handler can be identified by the handler type.

Handler types¶

A handler type belongs always to a group with a base type. Functions defined in the base type must be available in all subtypes. This ensures that a client with support for a base type can at least access the basic functionality of a handler even if that specific subtype isn’t supported.

The development process of an API can be classified by three states:

Experimental:: Currently under development and the API might be changed in the next release.
Beta:: The API should be changed only if there is a good reason for this.
Stable:: The existing API must not be changed.

To register a new handler type feel free to open a new request by using the issue tracker on github.

Start	End	Mask	Name	Status
0x0100	0x01FF	8	Base Pixel Strip	Beta
0x0180	0x01FF	9	Extended Pixel Strip	Experimental
0x0200	0x02FF	8	Base Matrix	Beta
0x0280	0x02FF	9	Extended Matrix	Beta
0x0300	0x03FF	8	Base Text-LCD	Experimental
0x0380	0x03FF	8	Extended Text-LCD	Experimental
0x0400	0x04FF	8	Base Sensor	Experimental
0x0401			Temperature Sensor	Experimental
0x0402			Humidity Sensor	Experimental
0x0403			Temperature-Humidity Sensor	Experimental
0x0500	0x05FF	8	Base Board	Experimental
0x0501		16	Arduino Board	Experimental
0xFF00	0xFFFF	8	Custom handlers	n/a

Base types¶

Base/Extended Pixel Strip¶

ID	Function	Strip Type
		Base	Extended
0x01	`pixel_strip::getColorCount()`	X	x
0x02	`pixel_strip::getPixelCount()`	X	x
0x11	`pixel_strip::setPixelColor()`	X	x
0x12	`pixel_strip::setRangeColor()`	X	x

uint8_t pixel_strip::getColorCount()¶

Get the number of colors. Return value should be 1, 2 or 3.

Returns:	Number of colors.

uint16_t pixel_strip::getPixelCount()¶

Get the number of available pixels.

Returns:	Number of pixels

void pixel_strip::setPixelColor(uint16_t n, uint8_t color1, uint8_t color2, uint8_t color3)¶

Set the color of a pixel. All color values MUST be given and spare colors will be ignored by the device.

Parameters:	n – The number of the LED. Range from 0 to pixel_count - 1 color1 – First color. Red if color_count = 3. color2 – Second color. Green if color_count = 3. color3 – Third color. Blue if color_count = 3.

void pixel_strip::setRangeColor(uint16_t start, uint16_t end, uint8_t color1, uint8_t color2, uint8_t color3)¶

Set the color of a range of pixels.

Parameters:	start – The position to start. Range from 0 to pixel_count - 1 end – The position to stop. Range from start to pixel_count - 1 color1 – First color. Red if color_count = 3. color2 – Second color. Green if color_count = 3. color3 – Third color. Blue if color_count = 3.

Base/Extended Matrix¶

The Base Matrix handler is inspired by the Adafruit_GFX library and it is intended to be used with libraries based on Adafruit_GFX. But it might also be possible to wrap any other library.

ID	Function	Matrix Type
		Base	Extended
0x01	`matrix_gfx::getColorCount()`	X	X
0x02	`matrix_gfx::getWidth()`	X	X
0x03	`matrix_gfx::getHeight()`	X	X
0x11	`matrix_gfx::drawPixel()`	X	X
0x21	`matrix_gfx::drawLine()`	X	X
0x22	`matrix_gfx::drawFastVLine()`		X
0x23	`matrix_gfx::drawFastHLine()`		X
0x24	`matrix_gfx::drawRect()`		X
0x25	`matrix_gfx::fillRect()`		X
0x26	`matrix_gfx::fillScreen()`	X	X
0x27	`matrix_gfx::invertDisplay()`		X
0x31	`matrix_gfx::drawCircle()`		X
0x32	`matrix_gfx::fillCircle()`		X
0x33	`matrix_gfx::drawTriangle()`		X
0x34	`matrix_gfx::fillTriangle()`		X
0x35	`matrix_gfx::drawRoundRect()`		X
0x36	`matrix_gfx::fillRoundRect()`		X
0x41	`matrix_gfx::drawChar()`		X
0x42	`matrix_gfx::setCursor()`		X
0x43	`matrix_gfx::setTextColor()`		X
0x44	`matrix_gfx::setTextColor()`		X
0x45	`matrix_gfx::setTextSize()`		X
0x46	`matrix_gfx::setTextWrap()`		X
0x47	`matrix_gfx::write()`		X
0x51	`matrix_gfx::setRotation()`		X
0x52	`matrix_gfx::swapBuffers()`		X
0x53	`matrix_gfx::setAutoSwapBuffers()`		X
0x61	`matrix_gfx::drawImage()`		X

uint8_t matrix_gfx::getColorCount()¶

Get the number of colors. Return value should be 1, 2 or 3.

Returns:	Number of colors.

uint16_t matrix_gfx::getWidth()¶

Get width in pixels.

Returns:	Number of pixels

uint16_t matrix_gfx::getHeight()¶

Get height in pixels.

Returns:	Number of pixels

void matrix_gfx::drawPixel(int16_t x, int16_t y, uint8_t color1, uint8_t color2, uint8_t color3)¶

Draw a pixel.

Parameters:	x – Pixel x position y – Pixel y position color1 – First color. Red if color_count = 3. color2 – Second color. Green if color_count = 3. color3 – Third color. Blue if color_count = 3.

void matrix_gfx::drawLine(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw a line.

void matrix_gfx::drawFastVLine(int16_t x, int16_t y, int16_t h, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw a vertical line.

void matrix_gfx::drawFastHLine(int16_t x, int16_t y, int16_t w, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw a horizontal line.

void matrix_gfx::drawRect(int16_t x, int16_t y, int16_t w, int16_t h, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw the boarder of rectangle.

void matrix_gfx::fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw a filled rectangle.

void matrix_gfx::fillScreen(uint8_t color1, uint8_t color2, uint8_t color3)¶: Fill the screen with the given color.

void matrix_gfx::invertDisplay(boolean i)¶: Invert the display.

void matrix_gfx::drawCircle(int16_t x0, int16_t y0, int16_t r, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw the border of a circle.

void matrix_gfx::fillCircle(int16_t x0, int16_t y0, int16_t r, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw a filled circle.

void matrix_gfx::drawTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw the boarder of a triangle.

void matrix_gfx::fillTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw a filled triangle.

void matrix_gfx::drawRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, int16_t radius, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw the boarder of a round rectangle.

void matrix_gfx::fillRoundRect(int16_t x0, int16_t y0, int16_t w, int16_t h, int16_t radius, uint8_t color1, uint8_t color2, uint8_t color3)¶: Draw a filled round rectangle.

void matrix_gfx::drawChar(int16_t x, int16_t y, unsigned char c, uint8_t color1, uint8_t color2, uint8_t color3, uint16_t bg, uint8_t size): Draw a character.

void matrix_gfx::setCursor(int16_t x, int16_t y)¶: Set the cursor position.

void matrix_gfx::setTextColor(uint8_t color1, uint8_t color2, uint8_t color3)¶: Set the text color.

void matrix_gfx::setTextColor(uint8_t color1, uint8_t color2, uint8_t color3, uint8_t bg_red, uint8_t bg_green, uint8_t bg_blue)¶: Set the text color.

void matrix_gfx::setTextSize(uint8_t s)¶: Set the text size.

void matrix_gfx::setTextWrap(boolean w)¶: Set the text wrap.

void matrix_gfx::setRotation(uint8_t r)¶: Set the rotation.

uint8_t matrix_gfx::swapBuffers(uint8_t copy)¶

Parameters copy:
	0 = False \| 1 = True

Swap buffers and copy new front buffer into the back buffer.

uint8_t matrix_gfx::setAutoSwapBuffers(uint8_t auto_swap)¶

Parameters auto_swap:
	0 = False \| 1 = True

Set option to swap buffers after each command.

void matrix_gfx::drawImage(int16_t x, int16_t y, int16_t width, int16_t height, uint8_t color_encoding, uint8_t *image)¶

Parameters:	x – x-position y – y-position width – Image width height – Image height color_encoding – The color encoding. For more information have a look at the list below. image – The image data

Color encoding:

Mode 0:

8-Bit encoding. From MSB to LSB:

2-Bit - red
3-Bit - green
3-Bit - blue

Mode 1:

16-Bit encoding. From MSB to LSB:

5-Bit - red
6-Bit - green
5-Bit - blue

Mode 2:

24-Bit encoding. From MSB to LSB:

8-Bit - red
8-Bit - green
8-Bit - blue

Base/Extended Text-LCD¶

ID	Function	Text-LCD Type
		Base	Extended
0x01	`text_lcd::getWidth()`	X	X
0x02	`text_lcd::getHeight()`	X	X
0x11	`text_lcd::clear()`	X	X
0x12	`text_lcd::home()`	X	X
0x13	`text_lcd::setCursor()`	x	X
0x21	`text_lcd::write()`	X	X
0x22	`text_lcd::print()`	X	X

uint8_t text_lcd::getWidth()¶: Get the width as number of characters.

uint8_t text_lcd::getHeight()¶: Get the height as number of characters.

void text_lcd::clear()¶: Clear the LCD screen and set the cursor position to the upper-left corner.

void text_lcd::home()¶: Set the cursor position to the upper-left corner.

void text_lcd::setCursor(uint8_t col, uint8_t row)¶

Parameters:	col – The column row – The row

Position the cursor.

void text_lcd::write(char c)¶

Parameters c:	The character to display

Print a single character to the LCD.

void text_lcd::print(uint8_t num, char[] text)

Parameters:	num – Number of characters text – The text to display

Print text to the LCD.

Base Sensor¶

Temperature/Humidity Sensor¶

The Temperature and the Humidity Sensors share the same API. Temperatures are always in Celsius.

ID	Function
0x11	`sensor_temperature::getMinValue()`
0x12	`sensor_temperature::getMaxValue()`
0x13	`sensor_temperature::getAccuracy()`
0x14	`sensor_temperature::getValue()`

float sensor_temperature::getMinValue()¶: Get the value of the lowest possible temperature/humidity measured by the sensor.

float sensor_temperature::getMaxValue()¶: Get the value of the highest possible temperature/humidity measured by the sensor.

float sensor_temperature::getAccuracy()¶: Get the best accuracy of the measured values.

float sensor_temperature::getValue()¶: Get the current temperature/humidity.

Temperature-Humidity Sensor¶

ID	Function
0x11	`sensor_temp_humidity::getMinTempValue()`
0x12	`sensor_temp_humidity::getMaxTempValue()`
0x13	`sensor_temp_humidity::getTempAccuracy()`
0x14	`sensor_temp_humidity::getTemperature()`
0x21	`sensor_temp_humidity::getMinHumidityValue()`
0x22	`sensor_temp_humidity::getMaxHumidityValue()`
0x23	`sensor_temp_humidity::getHumidityAccuracy()`
0x24	`sensor_temp_humidity::getHumidity()`

float sensor_temp_humidity::getMinTempValue()¶: Get the value of the lowest possible temperature measured by the sensor.

float sensor_temp_humidity::getMaxTempValue()¶: Get the value of the highest possible temperature measured by the sensor.

float sensor_temp_humidity::getTempAccuracy()¶: Get the best accuracy of the measured temperature.

float sensor_temp_humidity::getTemperature()¶: Get the current temperature.

float sensor_temp_humidity::getMinHumidityValue()¶: Get the value of the lowest possible humidity measured by the sensor.

float sensor_temp_humidity::getMaxHumidityValue()¶: Get the value of the highest possible humidity measured by the sensor.

float sensor_temp_humidity::getHumidityAccuracy()¶: Get the best accuracy of the measured humidity.

float sensor_temp_humidity::getHumidity()¶: Get the current humidity.

Base Board¶

At the moment only Arduino based boards are supported.

Arduino Board¶

A handler of this type is used to control Arduino based boards.

ID	Function
0x11	`board_arduino::getAnalogInput()`
0x21	`board_arduino::getDigitalInput()`
0x22	`board_arduino::setDigitalOutput()`
0x31	`board_arduino::setPWMOutput()`

uint16 board_arduino::getAnalogInput(uint8_t pin)¶

Get the value of an analog input pin.

Parameters pin:	Pin number

uint16 board_arduino::getDigitalInput(uint8_t pin)¶

Get the value of an digital input pin.

Parameters pin:	Pin number

uint16 board_arduino::setDigitalOutput(uint8_t pin, uint8_t value)¶

Set the value of a digital output pin.

Parameters:	pin – Pin number value – The value (0, 1)

uint16 board_arduino::setPWMOutput(uint8_t pin, uint8_t value)¶

Set the value of a PWM output pin.

Parameters:	pin – Pin number value – The PWM value (0-255)

Custom handlers¶

This range of IDs is reserved for custom handlers e.g. for testing or prototyping purposes.