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 in event_group was set:

Delete framebuffer_internal_old
Copy framebuffer_internal to framebuffer_internal_old
Delete framebuffer_internal
Copy framebuffer to framebuffer_internal
Delete internal_rendering_options
Copy rendering_options to internal_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

See: 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: flipdot_set_power

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.

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.

Public Members

uint8_t width¶: Panel width.

uint8_t x¶: Panel offset.

struct flipdot_configuration_t¶

Used to initialize a flipdot.

See: flipdot_initialize

Public Members

uint8_t panel_count¶: Number of attached panels.

uint8_t panel_size[(5)]¶: Width of the attached panels.

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

flipdot_set_power

Return

ESP_OK: success
ESP_ERR_INVALID_ARG: invalid arguments (i.e. null pointers)
ESP_ERR_NO_MEM: allocating internal buffers failed
other: failure

Parameters

flipdot: Flipdot to initialize, must not be NULL
flipdot_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 handle
power_status:
- True power on the flipdot
- False power off the flipdot

bool flipdot_get_power(flipdot_t *flipdot)¶

Returns if the flipdot is powered on.

Parameters

flipdot: The flipdot handle

esp_err_t flipdot_set_dirty_flag(flipdot_t *flipdot)¶: Notfies the flipdot task, that the framebuffer is dirty and needs redrawing.

Framebuffer¶

Framebuffer struct¶

struct framebuffer_t¶

A framebuffer with bottom left corner as x=0, y=0.

Public Members

uint16_t *columns¶: 16 pixels high columns

uint8_t width¶: Framebuffer width.

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 0
ESP_ERR_NO_MEM: failed to allocate memory

Parameters

framebuffer: The framebuffer_t* to initialize
width: 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 from
x: 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 manipulate
x: 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 encode
dst: Destination char buffer
dst_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 into
src: Source char buffer
src_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 1
b: Framebuffer 2
diff: 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 1
b: Framebuffer 2
start_x: X offset from where to start comparing
width: Width of the view port to compare
diff: 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.

struct flipdot_rendering_delay_options_t¶

Flipdot timing options.

Public Members

uint16_t pre_delay¶: How long to wait before rendering a column (in 10ms counts)

uint16_t clear_delay¶: How long to power the row high side drivers (in 10ms counts)

uint16_t set_delay¶: How long to power the column clear low side driver (in 10ms counts)

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 0
ESP_ERR_NO_MEM: could not allocate memory for internal data structures
ESP_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 0
width: 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 using calloc(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.