add firmware

firmware/main/include/lcd/ssd1306.h

@@ -0,0 +1,97 @@
+/**
+ * ============================================================================
+ * === SSD1306 128x64 IIC LCD Interface
+ * ============================================================================
+ * 
+ * Provides a simple interface for rendering text to an SSD1306 LCD.
+ * 
+ * digimint
+ */
+
+#pragma once
+
+#include "FontComicSansMS16.h"
+
+#include <freertos/FreeRTOS.h>
+#include <freertos/task.h>
+
+#include <stdbool.h>
+#include <stdint.h>
+
+// LCD target address
+#define IIC_LCD_ADDR (0x3C)
+
+#define LCD_TAG "LCD"
+
+extern uint8_t LCD_data[8][128];
+extern bool LCD_rowChanged[8];
+
+/**
+ * Initialize the LCD interface.
+ * 
+ * This command configures the IIC bus, sends the proper initialization commands
+ * to the LCD, and spawns a task to update the display regularly.
+ * 
+ * @param updateTaskHandle If this variable is not NULL, a handle to the display
+ *        update task will be stored in it.
+ */
+void LCD_init(TaskHandle_t* updateTaskHandle);
+
+
+/**
+ * Render a single character to the LCD buffer.
+ * 
+ * @warning This function does not perform bounds checking.
+ * 
+ * @param font The font to use for text rendering.
+ * @param oChr The character to render.
+ * @param x The x-coordinate for the top-left of the character.
+ * @param y The y-coordinate for the top-left of the character.
+ * @param invert Whether the character should be inverted before display.
+ */
+void LCD_renderChar(font_t font, const char oChr, uint16_t x, uint16_t y, bool invert);
+
+/**
+ * Render text to the LCD buffer.
+ * 
+ * @warning This function does not protect against buffer overrun.
+ * 
+ * @param font The font to use for text rendering.
+ * @param str The text to render.
+ * @param x The x-coordinate for the top-left of the first character.
+ * @param y The y-coordinate for the top-left of the first character.
+ * @param invert Whether the character should be inverted before display.
+ */
+void LCD_renderText(font_t font, const char* str, uint16_t x, uint16_t y, bool invert);
+
+/**
+ * Render text in Comic Sans
+ * 
+ * A convenience macro that expands to
+ * 
+ * `LCD_renderText(FontComicSansMS16, str, x, y);`
+ */
+static inline void LCD_renderTextCS(const char* str, uint16_t x, uint16_t y){
+    LCD_renderText(FontComicSansMS16, str, x, y, false);
+}
+
+/**
+ * Manually force an immediate update of the LCD.
+ * 
+ * Note that this function will be called automatically by the LCD update task
+ * during normal operation, so it generally should not be manually invoked.
+ * 
+ * A semaphore is used to ensure that only one task attempts to communicate with
+ * the display at a time.
+ * 
+ * @param block If true, then the calling task will block until the LCD is
+ *        available for communication. Otherwise, if the LCD is not immediately
+ *        available, the function will simply return `false`.
+ * 
+ * @return `true` if the LCD was successfully updated; `false` otherwise.
+ * 
+ * @note This function will only return false if two conditions apply:
+ *       (1) `block` is false; and
+ *       (2) The LCD semaphore has been taken (i.e. the LCD is currently busy)
+ */
+bool LCD_updateDisplay(bool block);