# citizenonex/frame_examples_python architecture

> Architecture diagram of the GitHub repository citizenonex/frame_examples_python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/citizenonex/frame_examples_python
- Repository: https://github.com/citizenonex/frame_examples_python

## Overview

##### Project type and purpose
- This is not a full-stack web app but a collection of example Python programs demonstrating two client libraries:
- frame-ble – sending display frames/commands over Bluetooth Low Energy to the “Brilliant Labs Frame” hardware
- frame-msg – sending frames/commands over a wired or serial connection
- The README makes it clear that each subfolder contains runnable sample scripts plus any embedded Lua payloads.

##### File structure
- Top-level:
- frame_ble/ – examples and Lua scripts for BLE transport
- frame_msg/ – examples and Lua scripts for serial/message-based transport
- README.md, LICENSE, .gitignore
- In each subfolder:
- Python scripts that import the package API, e.g. clear_display.py, send_break.py, audio_stream.py, camera.py, etc.
- A lua/ directory containing `.lua` scripts loaded by those Python clients
- requirements.txt listing the dependencies (frame-ble or frame-msg plus any helpers)

##### README for additional insights
- It instructs users to create a venv and run the examples from the terminal or VSCode.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Example Scripts Layers
    subgraph "BLE Example Scripts" 
        direction TB
        bd1["clear_display.py"]:::examples
        bd2["custom_lua_functions.py"]:::examples
        bd3["decompression.py"]:::examples
        bd4["echo.py"]:::examples
        bd5["hello_world.py"]:::examples
        bd6["reset_palette.py"]:::examples
        bd7["send_break.py"]:::examples
        bd8["send_reset.py"]:::examples
        bd9["stay_awake_false.py"]:::examples
        bd10["stay_awake_true.py"]:::examples
        ble_req["requirements.txt"]:::docs
    end

    subgraph "Serial/Message Example Scripts"
        direction TB
        sm1["audio_clip.py"]:::examples
        sm2["audio_stream.py"]:::examples
        sm3["audio_video_stream.py"]:::examples
        sm4["auto_exposure.py"]:::examples
        sm5["camera.py"]:::examples
        sm6["camera_sprite.py"]:::examples
        sm7["camera_sprite_loop.py"]:::examples
        sm8["code_value.py"]:::examples
        sm9["compress_decompress.py"]:::examples
        sm10["compressed_sprite_ind_png.py"]:::examples
        sm11["exposure_wb_algo_fw25.031.0924.py"]:::examples
        sm12["exposure_wb_algo_proposed.py"]:::examples
        sm13["imu.py"]:::examples
        sm14["live-camera-feed-with-params.py"]:::examples
        sm15["live-camera-feed.py"]:::examples
        sm16["manual_exposure.py"]:::examples
        sm17["metering.py"]:::examples
        sm18["multi_tap.py"]:::examples
        sm19["plain_text.py"]:::examples
        sm20["prog_sprite_jpg.py"]:::examples
        sm21["sprite_ind_png.py"]:::examples
        sm22["sprite_jpg.py"]:::examples
        sm23["sprite_move.py"]:::examples
        sm24["text_sprite_block.py"]:::examples
        msg_req["requirements.txt"]:::docs
    end

    %% Client Libraries
    subgraph "Client Libraries"
        direction TB
        lib_ble["frame-ble"]:::library
        lib_msg["frame-msg"]:::library
    end

    %% Transport Layer
    subgraph "Transport"
        direction TB
        ble_trans["BLE Radio Channel"]:::transport
        msg_trans["Serial/USB Channel"]:::transport
    end

    %% Hardware Device
    subgraph "Brilliant Labs Frame Device"
        direction TB
        device["Frame Hardware"]:::hardware
        lua_vm["Lua VM"]:::vm
    end

    %% Lua Payloads
    subgraph "Embedded Lua Payloads"
        direction TB
        lua_ble_dir["BLE Lua Scripts"]:::payload
        fib["fibonacci.lua"]:::payload
        lua_msg_dir["Message Lua Scripts"]:::payload
    end

    %% Connections
    bd1 -->|uses API| lib_ble
    bd2 -->|uses API| lib_ble
    bd3 -->|uses API| lib_ble
    bd4 -->|uses API| lib_ble
    bd5 -->|uses API| lib_ble
    bd6 -->|uses API| lib_ble
    bd7 -->|uses API| lib_ble
    bd8 -->|uses API| lib_ble
    bd9 -->|uses API| lib_ble
    bd10 -->|uses API| lib_ble
    lib_ble -->|sends frames| ble_trans
    ble_trans -->|transmits| device
    device -->|executes| lua_vm
    lua_vm -->|runs| fib
    fib -->|origin| lua_ble_dir

    sm1 -->|uses API| lib_msg
    sm2 -->|uses API| lib_msg
    sm3 -->|uses API| lib_msg
    sm4 -->|uses API| lib_msg
    sm5 -->|uses API| lib_msg
    sm6 -->|uses API| lib_msg
    sm7 -->|uses API| lib_msg
    sm8 -->|uses API| lib_msg
    sm9 -->|uses API| lib_msg
    sm10 -->|uses API| lib_msg
    sm11 -->|uses API| lib_msg
    sm12 -->|uses API| lib_msg
    sm13 -->|uses API| lib_msg
    sm14 -->|uses API| lib_msg
    sm15 -->|uses API| lib_msg
    sm16 -->|uses API| lib_msg
    sm17 -->|uses API| lib_msg
    sm18 -->|uses API| lib_msg
    sm19 -->|uses API| lib_msg
    sm20 -->|uses API| lib_msg
    sm21 -->|uses API| lib_msg
    sm22 -->|uses API| lib_msg
    sm23 -->|uses API| lib_msg
    sm24 -->|uses API| lib_msg
    lib_msg -->|sends frames| msg_trans
    msg_trans -->|transmits| device
    device -->|executes| lua_vm
    lua_vm -->|runs all| lua_msg_dir

    %% Documentation
    ble_req --> lib_ble
    msg_req --> lib_msg

    %% Click Events
    click bd1 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/clear_display.py"
    click bd2 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/custom_lua_functions.py"
    click bd3 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/decompression.py"
    click bd4 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/echo.py"
    click bd5 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/hello_world.py"
    click bd6 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/reset_palette.py"
    click bd7 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/send_break.py"
    click bd8 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/send_reset.py"
    click bd9 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/stay_awake_false.py"
    click bd10 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/stay_awake_true.py"
    click ble_req "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/requirements.txt"
    click sm1 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/audio_clip.py"
    click sm2 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/audio_stream.py"
    click sm3 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/audio_video_stream.py"
    click sm4 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/auto_exposure.py"
    click sm5 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/camera.py"
    click sm6 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/camera_sprite.py"
    click sm7 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/camera_sprite_loop.py"
    click sm8 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/code_value.py"
    click sm9 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/compress_decompress.py"
    click sm10 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/compressed_sprite_ind_png.py"
    click sm11 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/exposure_wb_algo_fw25.031.0924.py"
    click sm12 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/exposure_wb_algo_proposed.py"
    click sm13 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/imu.py"
    click sm14 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/live-camera-feed-with-params.py"
    click sm15 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/live-camera-feed.py"
    click sm16 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/manual_exposure.py"
    click sm17 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/metering.py"
    click sm18 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/multi_tap.py"
    click sm19 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/plain_text.py"
    click sm20 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/prog_sprite_jpg.py"
    click sm21 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/sprite_ind_png.py"
    click sm22 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/sprite_jpg.py"
    click sm23 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/sprite_move.py"
    click sm24 "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/text_sprite_block.py"
    click msg_req "https://github.com/citizenonex/frame_examples_python/blob/main/frame_msg/requirements.txt"
    click lua_ble_dir "https://github.com/citizenonex/frame_examples_python/tree/main/frame_ble/lua/"
    click fib "https://github.com/citizenonex/frame_examples_python/blob/main/frame_ble/lua/fibonacci.lua"
    click lua_msg_dir "https://github.com/citizenonex/frame_examples_python/tree/main/frame_msg/lua/"

    %% Styles
    classDef examples fill:#e0ffe0,stroke:#2d7930,color:#000
    classDef library fill:#e0f0ff,stroke:#305d79,color:#000
    classDef transport fill:#ffe0b3,stroke:#b36b00,color:#000
    classDef hardware fill:#f0f0f0,stroke:#666666,color:#000
    classDef vm fill:#f9e0ff,stroke:#8a2be2,color:#000
    classDef payload fill:#fff0e0,stroke:#c06020,color:#000
    classDef docs fill:#f2f2f2,stroke:#999999,color:#000
```
