DeskHog Documentation

DeskHog uses a system of Card Definitions and Card Configurations to manage the UI.

1. Card Definitions (CardDefinition) represent the available types of cards (e.g., a PostHog Insight) that a user can choose to add. These are registered in the CardController and include a factory function to create the UI component.
2. Card Configurations (CardConfig) represent the active instances of cards currently displayed on the screen. These are stored in persistent memory as a JSON array.

When a user modifies their configuration via the Web UI or API, the CardController performs a reconciliation: it diffs the new configuration against the currently displayed cards, removes obsolete ones, creates new ones using their registered factory functions, and re-orders the CardNavigationStack to match the new order.

// Example of the relationship between a definition and a config
// A definition tells you WHAT can be added
struct CardDefinition {
    CardType id;
    String name;
    bool allowMultiple;
    bool needsConfigInput;
    String configInputLabel;
    String uiDescription;
    std::function<lv_obj_t*(const String& configValue)> factory;
};

// A config tells you WHAT IS currently active
struct CardConfig {
    CardType id;
    String config; // e.g., insight ID, animation speed
    int order;
};

The DeskHog card architecture is an extensible system designed for dynamic card management via a web UI. Instead of direct integration in the main loop, cards are managed through a factory pattern and a standardized interface.

Key components include:

• CardType enum: Defines the available card types.
• CardDefinition: Metadata describing a card (name, UI description, configuration needs).
• Factory Pattern: Uses lambda functions to instantiate cards dynamically.
• InputHandler interface: The base class that all cards must implement to handle user input and lifecycle events.
• Dynamic Management: Cards can be added or removed at runtime through the web interface.

// Conceptual relationship: CardDefinition uses a factory lambda to create InputHandler instances
flappyDef.factory = [this](const String& configValue) -> lv_obj_t* {
    // ... returns the UI object (lv_obj_t*)
};

For cards requiring high-frequency updates (games, animations, or real-time visualizations), inherit from InputHandler. This allows you to hook into the UI system's update loop without creating new tasks or timers.

1. Inherit from InputHandler: Implement handleButtonPress(uint8_t button_index), update(), and prepareForRemoval().
2. The update() method: This is called approximately 60 times per second when the card is active/visible. Return true to continue receiving updates, or false to stop.
3. Registration: In your CardDefinition factory, call cardStack->registerInputHandler(card_object, handler_instance) to link the LVGL object to your logic class.

This approach maintains thread safety by working within the existing UI task and automatically stops updates when the card is no longer visible.

// 1. Your card class should inherit from InputHandler
class FlappyHogCard : public InputHandler {
public:
    // Handle button presses (required by InputHandler)
    bool handleButtonPress(uint8_t button_index) override {
        // Return false to allow navigation, true if you handled it
        return false;
    }
    
    // Update method for game logic (called ~60 times per second)
    bool update() override {
        if (game) {
            game->loop();  // Update game state
            return true;   // Continue receiving updates
        }
        return false;
    }
    
    // Required for proper cleanup
    void prepareForRemoval() override {
        // Called before LVGL object deletion
    }
};

// 2. Register the card with an InputHandler
helloDef.factory = [this](const String& configValue) -> lv_obj_t* {
    FlappyHogCard* newCard = new FlappyHogCard(screen);
    if (newCard && newCard->getCard()) {
        // Register as InputHandler to receive updates
        cardStack->registerInputHandler(newCard->getCard(), newCard);
        return newCard->getCard();
    }
    delete newCard;
    return nullptr;
};

The captive portal UI (portal.html and portal.js) must be extended to allow users to trigger and monitor updates.

Required HTML Elements (portal.html)

• #current-version: Displays current firmware version.
• #available-version: Displays version found on GitHub.
• #check-update-btn: Triggers the update check.
• #install-update-btn: Triggers the installation (initially hidden).
• #release-notes: Displays release notes from the GitHub API.
• #update-status-container & #update-progress-bar: Visual feedback for the update process.
• #update-error-message: Displays error details.

Required JavaScript Logic (portal.js)

• checkFirmwareUpdate(): Fetches /check-update to populate version info and show the install button.
• startFirmwareUpdate(): POSTs to /start-update to begin the process.
• pollUpdateStatus(): Periodically fetches /update-status to update the progress bar and status message.

DeskHog uses a png2c.py script to convert PNG images into LVGL-compatible ARGB8888 C arrays. This is useful for adding sprite-based animations.

Workflow

1. Organize Files: Place PNG files in subdirectories under raw-png/. Each subdirectory will become a named array in the generated code. Example structure:

   raw-png/
   ├── walking/
   │   ├── frame_01.png
   │   └── frame_02.png
   └── idle/
       └── idle_01.png

2. Run Conversion: Execute the script from your terminal:

   python3 png2c.py

3. Use in Code: Include include/sprites/sprites.h. The script generates an array for each directory and a corresponding _count variable.

Requirements

• Python 3
• Pillow and numpy libraries (pip install Pillow numpy)

Usage Example

#include "sprites/sprites.h"

// Access the walking animation array
lv_obj_t* img = lv_img_create(parent);
lv_img_set_src(img, &walking_sprites[0]);  // First frame

// Animate through frames
for (int i = 0; i < walking_sprites_count; i++) {
    lv_img_set_src(img, &walking_sprites[i]);
    // Add delay or use LVGL animation
}

The DeskHog uses a dynamic card system managed by CardController. To add a new card type, follow these four steps:

1. Update the Enum: Add your new type to the CardType enum in src/ui/CardController.h.
2. Implement the Class: Create a new class that implements the card UI using the LVGL library.
3. Register the Card: Add the card to the CardController::initializeCardTypes() method using a CardDefinition.
4. Add Configuration (Optional): Implement support if your card requires user input via the Web UI.

CardDefinition Properties

When registering a card, you must provide a CardDefinition object with these properties:

• type: Unique CardType enum value.
• name: The display name shown in the Web UI.
• allowMultiple: Boolean indicating if users can add multiple instances.
• needsConfigInput: Boolean indicating if the card requires configuration.
• configInputLabel: The label for the configuration input field (if needsConfigInput is true).
• uiDescription: A description shown in the Web UI.
• factory: A lambda function (const String& configValue) -> lv_obj_t* that instantiates the card.

// 1. Add to CardType enum (src/ui/CardController.h)
enum class CardType {
    INSIGHT = 0,
    FRIEND = 1,
    HELLO = 2  // Add your new type here
};

// 2. Create your card class (src/ui/HelloCard.h)
class HelloCard {
public;
    HelloCard(lv_obj_t* parent);
    lv_obj_t* getCard() const { return _card; }

private:
    lv_obj_t* _card;
};

// 3. Register in CardController::initializeCardTypes()
CardDefinition helloDef;
helloDef.type = CardType::HELLO;
helloDef.name = "Hello world";
helloDef.allowMultiple = true;
helloDef.needsConfigInput = false;
helloDef.uiDescription = "A simple greeting card";
helloDef.factory = [this](const String& configValue) -> lv_obj_t* {
    HelloCard* newCard = new HelloCard(screen);
    return newCard ? newCard->getCard() : nullptr;
};
registerCardType(helloDef);