-
Notifications
You must be signed in to change notification settings - Fork 1
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.handmodule_actions_t) - define an icon for your module
- use some convenience functions (
lib/modules.handcommon.h)
Additionally, it's possible to interact with different sensors and builtins. This section describes only the most important functions.
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.
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
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.
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.
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.
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.
void xxx_redraw(const uint8_t force);
If force is set, the module must redraw its area (perhaps it was just swtched to).
Some modules can interact with the user through buttons. Every time the user presses select, its select action is called:
module_actions_t *xxx_select(const uint8_t state);
The select handler may return NULL or module_actions_t. If it returns NULL, nothing happens.
However, 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 - for an example see the modules/config.c module.
To restore default actions, use module_actions_t default_actions from actions.h.
All button handlers receive the state of the button after it's pressed. 0 signifies pressed in, 1 is released.
Apart from libraries and action handlers, the API includes a set of signals. Additionally, some sensors and builtins expose their own useful interfaces.
extern volatile uint16_t wheel_pulse_table[WHEEL_PULSE_TABLE_SIZE];
extern volatile uint8_t wheel_pulse_count;
The pulse table stores the time of a few most revent pulses, together with theit count. It gets cleared at every wheel stop.
extern volatile uint16_t crank_pulse_times[CRANK_PULSES];
extern volatile uint8_t crank_pulse_count;
Twin data of the wheel sensor, applied to crank.
uint16_t millimeters_pulse_distance;
uint16_t pulse_dist;
These values store pulse distance in metric and as used internally by the distance subsystem.
void update_pulse_distance(void);
Function updating the pulse distance values - present only when pulse distance is not constant.
void speed_update_factor(void);
Function to update internal speed factors after the pulse distance changed. Present only when pulse distance is not constant.
uint16_t get_average_speed(const uint16_t time_amount, const uint8_t pulse_count);
uint16_t get_average_speed_long(uint32_t time_amount, const uint16_t pulse_count);
Two convenience functions to quickly calculate the speed. the _long flavor is present only when LONG_CALCULATIONS is present.