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
0x0181			Adafruit_NeoPixel	Experimental
0x0200	0x02FF	8	Base/Extended Matrix	Beta
0x0280	0x02FF	9	Base/Extended Matrix	Beta
0x0281			Colorduino_GFX	Experimental
0xFF00	0xFFFF	8	Custom handlers	n/a

Base types

Base Pixel Strip

ID	Function
0x01	base_pixel_strip::getColorCount()
0x02	base_pixel_strip::getPixelCount()
0x11	base_pixel_strip::setPixelColor()
0x12	base_pixel_strip::setRangeColor()

uint8_t base_led_strip::getColorCount()

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

Returns:Number of colors.

uint16_t base_led_strip::getPixelCount()

Get the number of available pixels.

Returns:Number of pixels

void base_led_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 base_led_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.

Extended Pixel Strip

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
0x10	matrix_gfx::drawPixel()	X	X
0x20	matrix_gfx::drawLine()	X	X
0x21	matrix_gfx::drawFastVLine()		X
0x22	matrix_gfx::drawFastHLine()		X
0x23	matrix_gfx::drawRect()		X
0x24	matrix_gfx::fillRect()		X
0x25	matrix_gfx::fillScreen()	X	X
0x26	matrix_gfx::invertDisplay()		X
0x30	matrix_gfx::drawCircle()		X
0x31	matrix_gfx::fillCircle()		X
0x32	matrix_gfx::drawTriangle()		X
0x33	matrix_gfx::fillTriangle()		X
0x34	matrix_gfx::drawRoundRect()		X
0x35	matrix_gfx::fillRoundRect()		X
0x40	matrix_gfx::drawChar()		X
0x41	matrix_gfx::setCursor()		X
0x42	matrix_gfx::setTextColor()		X
0x43	matrix_gfx::setTextColor()		X
0x44	matrix_gfx::setTextSize()		X
0x45	matrix_gfx::setTextWrap()		X
0x46	matrix_gfx::write()		X
0x50	matrix_gfx::setRotation()		X
0x51	matrix_gfx::drawBitmap()		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.

void matrix_gfx::drawBitmap(int16_t x, int16_t y, const uint8_t* bitmap, int16_t w, int16_t h, uint8_t color1, uint8_t color2, uint8_t color3)

Draw a Bitmap.

Colorduino_GFX

This handler extends Base/Extended Matrix.

ID	Function
0xA0	swapBuffers()
0xA1	setAutoSwapBuffers()

uint8_t swapBuffers(uint8_t copy)

Parameters copy:  0 = False | 1 = True

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

uint8_t setAutoSwapBuffers(uint8_t auto_swap)

Parameters auto_swap:  0 = False | 1 = True

Set option to swap buffers after each command.

Custom handlers

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