API

The module API allows you to:

• draw on the screen & to buffers (display/drawing.h, display/pcd8544.h)
• collect and draw graph data (builtins/plot.h)
• discover current time and set timer callbacks (lib/timer.h)
• perform speed calculations (lib/calculations.h)
• set up your own button handlers (actions.h and module_actions_t)
• define an icon for your module
• use some convenience functions (lib/modules.h and common.h)

Additionally, it's possible to interact with different sensors and builtins. This section describes only the most important functions.

display/drawing.h

void print_number(uint32_t bin, upoint_t position, const upoint_t glyph_size, const uint8_t width, const number_display_t digits);

This function prints a number bin at 8-pixel line position.y (top = 0) and position.x pixels from the left edge of the screen. glyph_size is the width of a single character measured in pixels, width is the thickness of the brush to draw lines. digits is composed of 2 nibbles: x is number of digits before decimal point, y is fraction size.

Since bin is an integer, the decimal place is purely cosmetic: if 1280 is passed with fraction size == 0, it is interpreted as 1280. If fraction size == 1, then it's interpreted as 128.0. The last integer digit is always displayed and the decimal representation is padded with spaces to always place the decimal point in the same place (equal to value of x in digits), e.g. with digits == (number_display_t){.integer=3, .fractional=2}, 12345 becomes 123.45, 5556 is displayed as _55.56, 345 becomes __3,45, 19 becomes __0.19, 3 is __0.03 and 0 is __0.00. An exception to this rule is if decimal representation is longer than expected - in this case, the whole number will be displayed.

display/pcd8544.h

void set_column(const uint8_t col)

Set the display module to a specified column.

void set_row(const uint8_t row)

Set the display module to a specified 8px row.

void send_raw_byte(const uint8_t payload, const uint8_t data)

Low-level function for communicating with the display module. Useful for drawing bitmaps:

set_column(0); // set display to the left edge of the screen
set_row(0); // display at the top of the screen
send_raw_byte(0b01010111, true); // send a column of 8 pixels to the display at current position
                                 // remember to set data=true or it will be sent as a command

lib/plots.h

circular_buffer_t

Structure containing PLOT_SIZE values of type uint8_t. Upon adding a value, the oldest one may be erased.

void circular_buffer_insert_value(circular_buffer_t *buffer, const uint8_t value)

Inserts a value into the buffer.

void draw_circular_buffer_plot_line(const circular_buffer_t buffer, const uint8_t line)

Draws a single line number line of a circular buffer buffer. To draw a complete plot, look at lib/modules.h.

lib/modules.h

typedef struct module_record {
    void (*redraw)(uint8_t force);
    module_actions_t* (*select_button)(uint8_t state);
    char signature[MODULE_SIGNATURE_SIZE];
} module_record_t;

The data structure defining default actions of a module. redraw takes one parameter, force, which is true if the whole module area must be updated. select_button is called when user selects the module. Its return value becomes the new binding of buttons. If the return value is NULL however, no action is taken.

void erase_screen(uint8_t count);

clears count columns in front of cursor

void erase_module_screen(void);

void draw_circular_buffer_plot(const circular_buffer_t buffer);

Draws the circular buffer buffer as a plot in the module area.

module_actions_t* module_select_null(const uint8_t state);

Always returns NULL. Meant to be used with non-interactive modules.

lib/timer.h

uint16_t get_time(void);
uint32_t get_extended_time(void);

Functions return time at the moment of the call.

timer_handle_t timer_set_callback(const uint16_t time, void (*callback)(void));

Schedules callback to be called at time. Returns a timer handle that can be used to cancel the event.

void timer_clear_callback(const timer_handle_t identifier);

Clears the callback scheduled by identifier.

Calculations

uint16_t get_rot_speed(const uint32_t pulse_distance, const uint16_t time_amount, const uint8_t pulse_count);
uint16_t get_rot_speed_long(const uint32_t pulse_distance, uint32_t time_amount, const uint16_t pulse_count);

Functions to calculate rotational speed. Internally, they calculate (pulse_distance * pulse_count / time_amount) >> FRAC_BITS value. pulse_distance is the distance between pulses with FRAC_BITS fractional bits, time_amount is the total time elapsed between pulses, pulse_count is pulse count... Note: get_rot_speed_long is only present if LONG_CALCULATIONS is enabled.

Functions calculate speed, discovering distance using pulse_count. By default, the unit of speed is 0.1 km/h. get_int_average_long is only available when LONG_SPEED is defined, as its program memory footprint is considerably large.

Callback functions

void xxx_redraw(const uint8_t force);

If force is set, the module must redraw its area (perhaps it was just swtched to).

module_actions_t *xxx_select(const uint8_t state);

All button handlers receive the state of the button after it's pressed. 0 signifies pressed in, 1 is released. The select handler may return NULL or module_actions_t. If it returns NULL, default actions are restored (module switching).

Action handlers

If xxx_select reuturns module_actions_t, these actions are hooked to button handlers instead of the default ones. It becomes possible to implement submodules or interaction within a module. Returning NULL on select handler restores default actions. Untested and may improve in the future.

Convenience functions

Many modules make no use of the select feature. Theu can use a generic implementation:

module_actions_t *module_select_null(const uint8_t state) {
    return NULL;
}

void erase_module_screen(void);

Erases the whole module screen.