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.