Flipdot API reference¶
Flipdot¶
Flipdot structs¶
-
struct
flipdot_t
¶ Main flipdot data structure Passed as a pointer to most of the flipdot functions.
Public Members
-
EventGroupHandle_t
event_group
¶ Used for inter task communication with the flipdot task.
-
TaskHandle_t *
task
¶ Flipdot rendering task Performs the following actions, when
FLIPDOT_FRAMEBUFFER_DIRTY_BIT
inevent_group
was set:Delete
framebuffer_internal_old
Copy
framebuffer_internal
toframebuffer_internal_old
Delete
framebuffer_internal
Copy
framebuffer
toframebuffer_internal
Delete
internal_rendering_options
Copy
rendering_options
tointernal_rendering_options
Render the flipdot as configured
-
framebuffer_t *
framebuffer
¶ You can manipulate this framebuffer as you please.
Once done, call
flipdot_set_dirty_flag
-
framebuffer_t *
framebuffer_internal
¶ Internal framebuffer, used to avoid race conditions when rendering.
-
framebuffer_t *
framebuffer_internal_old
¶ Previous internal framebuffer, used for differential rendering.
-
flipdot_panel_t *
panels
¶ Panel configuration.
-
uint8_t
panel_count
¶ Number of attached panels.
-
uint8_t
width
¶ Total flipdot width in pixels.
-
flipdot_rendering_options_t *
rendering_options
¶ Rendering options.
-
flipdot_rendering_options_t *
internal_rendering_options
¶ Internal rendering options, used internally to avoid race conditions when rendering.
-
bool
power_status
¶ Flipdot power status.
- Note
Use
flipdot_set_power
to manipulate this member- See
-
spi_device_handle_t
spi_device_handle
¶ SPI device handle.
- Note
SPI is used for controlling shift registers IC5, IC6 and IC7.
-
flipdot_io_state_t
io
¶ Flipdot GPIO state, used for shifting out IO states via SPI to IC5, IC6 and IC7.
-
unsigned long long
pixels_flipped
¶ Counts the pixels that changed their color since startup.
-
SemaphoreHandle_t
semaphore
¶ Used for mutual exclusive hardware access.
-
EventGroupHandle_t
-
struct
flipdot_panel_t
¶ Location and size of a flipdot panel.
A flipdot consists of up to 5 panels. Width of a panel is typically 20 or 25 pixels. Height is hardcoded to be 16.
-
struct
flipdot_configuration_t
¶ Used to initialize a flipdot.
Flipdot functions¶
-
esp_err_t
flipdot_initialize
(flipdot_t *flipdot, flipdot_configuration_t *flipdot_configuration)¶ Initializes a flipdot for use and starts the flipdot task.
- Note
To actually use the flipdot you have to power it up using flipdot_set_power.
- See
- Return
ESP_OK
: successESP_ERR_INVALID_ARG
: invalid arguments (i.e. null pointers)ESP_ERR_NO_MEM
: allocating internal buffers failedother: failure
- Parameters
flipdot
: Flipdot to initialize, must not be NULLflipdot_configuration
: Configuration to apply, must not be NULL
-
esp_err_t
flipdot_set_power
(flipdot_t *flipdot, bool power_status)¶ Power on / off the flipdot.
- Note
This does not stop the rendering task
- Return
ESP_OK success
ESP_TIMEOUT timeout waiting for flipdot->semaphore
- Parameters
flipdot
: The flipdot handlepower_status
:True power on the flipdot
False power off the flipdot
Framebuffer¶
Framebuffer struct¶
-
struct
framebuffer_t
¶ A framebuffer with bottom left corner as x=0, y=0.
-
esp_err_t
flipdot_framebuffer_init
(framebuffer_t *framebuffer, uint8_t width)¶ Initialize a framebuffer.
- Return
ESP_ERR_INVALID_ARG
: framebuffer was NULL or width was 0ESP_ERR_NO_MEM
: failed to allocate memory
- Parameters
framebuffer
: The framebuffer_t* to initializewidth
: Framebuffer width. Must be > 0
-
void
flipdot_framebuffer_free
(framebuffer_t *framebuffer)¶ Free a framebuffer_t* Framebuffer is freed and the pointer set to NULL to avoid use after free bugs.
- Parameters
framebuffer
: The framebuffer to free
Framebuffer manipulation¶
-
void
flipdot_framebuffer_clear
(framebuffer_t *framebuffer)¶ Clear a framebuffer (set all pixels dark)
- Parameters
framebuffer
: The framebuffer to clear
-
bool
flipdot_framebuffer_get_pixel
(framebuffer_t *framebuffer, uint8_t x, uint8_t y)¶ Get a single pixel value.
- See
framebuffer_t for an explanation of the coordinate system
- See
framebuffer_t for an explanation of the coordinate system
- Return
true Pixel is set (bright)
false Pixel is not set (dark) or out of bounds read or framebuffer was NULL
- Parameters
framebuffer
: The framebuffer to retrieve pixel value fromx
: X location,
- Parameters
y
: Y location,
-
esp_err_t
flipdot_framebuffer_set_pixel
(framebuffer_t *framebuffer, uint8_t x, uint8_t y, bool value)¶ Set a single pixel value.
- See
framebuffer_t for an explanation of the coordinate system
- See
framebuffer_t for an explanation of the coordinate system
- Return
ESP_OK success
ESP_ERR_INVALID_ARG out of bounds or framebuffer was NULL
- Parameters
framebuffer
: The framebuffer to manipulatex
: X location,
- Parameters
y
: Y location,
- Parameters
value
:true Pixel is set (bright)
false Pixel is not set (dark) or out of bounds read
Framebuffer de/encoding¶
-
char *
flipdot_framebuffer_encode_line
(framebuffer_t *framebuffer, char *dst, size_t dst_len, uint8_t y)¶ ASCII encode a horizontal framebuffer line.
- Return
NULL failure
char* Pointer to the encoded line
- Note
- See
flipdot_framebuffer_encode_pixel is used for ASCII encoding single pixels
- Parameters
framebuffer
: The framebuffer to encodedst
: Destination char bufferdst_len
: Destination buffer size, must be framebuffer->width + 1 to accomodate the trailing 0 character
-
esp_err_t
flipdot_framebuffer_decode_line
(framebuffer_t *framebuffer, char *src, size_t src_len, uint8_t y)¶ ASCII decode a horizontal framebuffer line.
- Return
ESP_OK success
ESP_INVALID_ARG framebuffer was null, or src_len != framebuffer->width + 1
- Note
- See
flipdot_framebuffer_decode_pixel is used for ASCII decoding single pixels
- Parameters
framebuffer
: The framebuffer to decode intosrc
: Source char buffersrc_len
: Source buffer size, must be framebuffer->width + 1 to accomodate the trailing 0 character
-
char
flipdot_framebuffer_encode_pixel
(bool value)¶ ASCII encode a single pixel.
- Return
- See
FLIPDOT_PIXEL_SET pixel is set
- See
FLIPDOT_PIXEL_CLEAR pixel is not set
- Parameters
value
: The pixel value to encode
-
bool
flipdot_framebuffer_decode_pixel
(char src)¶ ASCII decode a single pixel.
- Return
true pixel is set (src == FLIPDOT_PIXEL_SET)
false pixel is not set (all other cases)
- Parameters
src
: Character to decode into a pixel value
-
esp_err_t
flipdot_framebuffer_printf
(framebuffer_t *framebuffer)¶ Printf the given framebuffer to STDOUT.
- Return
ESP_OK success
ESP_ERR_INVALID_ARG framebuffer was NULL
ESP_ERR_NO_MEM could not allocate enough memory
- Parameters
framebuffer
: The framebuffer to print
Framebuffer diffing¶
-
esp_err_t
flipdot_framebuffer_compare
(framebuffer_t *a, framebuffer_t *b, unsigned int *diff)¶ Compares two framebuffers.
- Return
ESP_INVALID_ARG a was NULL and / or b was NULL and / or diff was NULL and / or a->width != b->width
ESP_OK success
- Parameters
a
: Framebuffer 1b
: Framebuffer 2diff
: Pointer to an integer to store the number of changed pixels
-
esp_err_t
flipdot_framebuffer_compare_partial
(framebuffer_t *a, framebuffer_t *b, uint8_t start_x, uint8_t width, unsigned int *diff)¶ Compares two framebuffers partially.
- Return
ESP_INVALID_ARG a was NULL and / or b was NULL and / or diff was NULL and / or a->width != b->width and / or a->width < start_x + width
ESP_OK success
- Parameters
a
: Framebuffer 1b
: Framebuffer 2start_x
: X offset from where to start comparingwidth
: Width of the view port to comparediff
: Pointer to an integer to store the number of changed pixels
Rendering options¶
-
struct
flipdot_rendering_options_t
¶ Flipdot rendering options.
Public Members
-
uint8_t
width
¶ Flipdot width.
-
uint8_t
panel_count
¶ Number of panels attached to flipdot.
-
flipdot_rendering_mode_t
mode
¶ Flipdot rendering mode.
-
flipdot_rendering_delay_options_t *
delay_options
¶ Flipdot timing options.
-
uint8_t *
panel_order
¶ Order in which panels are rendered.
-
uint8_t
-
struct
flipdot_rendering_delay_options_t
¶ Flipdot timing options.
-
enum
flipdot_rendering_mode_t
¶ Values:
-
FULL
= 0¶ Always render the full framebuffer without skipping anything.
-
DIFFERENTIAL
= 1¶ Redraw only those pixels that changed.
-
-
esp_err_t
flipdot_rendering_options_initialize
(flipdot_rendering_options_t *rendering_options, uint8_t panel_count, uint8_t width)¶ Allocates internal data structures and initializes them with reasonable defaults.
- Return
ESP_ERR_INVALID_ARG
: rendering_options was NULL, panel_count was 0 or width was 0ESP_ERR_NO_MEM
: could not allocate memory for internal data structuresESP_OK
: success
- Parameters
options
: The flipdot_rendering_options_t to initialize, must not be NULL.panel_count
: Number of panels available, must be larger than 0width
: Number of columns available, must be larger than 0
-
esp_err_t
flipdot_rendering_options_copy
(flipdot_rendering_options_t *dest, flipdot_rendering_options_t *src)¶ Copies rendering options from src to dest.
- Parameters
dest
: Allocate usingcalloc(1, sizeof(flipdot_rendering_options_t))
src
: Source
-
void
flipdot_rendering_options_free
(flipdot_rendering_options_t *rendering_options)¶ Free a flipdot_rendering_options_t*.
- Parameters
rendering_options
: flipdot_rendering_options_t* to free.