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¶
- 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.