# bulebots/bulebule architecture

> Architecture diagram of the GitHub repository bulebots/bulebule, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bulebots/bulebule
- Repository: https://github.com/bulebots/bulebule

## Overview

Bulebule is a micromouse robot: the user configures a search goal and speed, the firmware explores and saves a maze, then can reuse that maze for a run. The sampled entry point shows orchestration and hardware setup; several algorithm implementations live in the listed but unsampled `src/mmlib` submodule, so their internal calls are not inferred. The repository also includes Bluetooth/data-analysis tools. Edges reflect calls shown in `src/main.c`, explicit README scope, or the indexed import from the Bluetooth tool.

Main entry points: [`src/main.c`](https://github.com/bulebots/bulebule/blob/master/src/main.c) (Firmware orchestration), [`src/setup.c`](https://github.com/bulebots/bulebule/blob/master/src/setup.c) (Board initialization), [`scripts/connect_bluetooth.py`](https://github.com/bulebots/bulebule/blob/master/scripts/connect_bluetooth.py) (Bluetooth client), [`src/eeprom.c`](https://github.com/bulebots/bulebule/blob/master/src/eeprom.c) (Saved maze storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Robot workflow"]
  node_main["Firmware orchestration<br/>[main.c]"]
  node_search["Maze exploration and run"]
  node_motion["Motion and motor control"]
  node_hmi["Buttons and interface"]
  node_maze_store[("Saved maze storage<br/>[eeprom.c]")]
  node_simulation["Simulation movement<br/>[move.c]"]
end

subgraph group_hardware["Robot hardware"]
  node_setup["Board initialization<br/>[setup.c]"]
  node_sensing["Infrared sensing<br/>[detection.c]"]
  node_motor_driver["Motor driver<br/>[motor.c]"]
  node_battery["Battery monitoring<br/>[voltage.c]"]
end

subgraph group_connectivity["Connectivity and analysis"]
  node_bluetooth["Bluetooth serial<br/>[serial.c]"]
  node_bluetooth_tool["Bluetooth client"]
  node_analysis["Log analysis<br/>[analysis.py]"]
  node_simulation_client["Simulation client"]
end

node_user(("Robot operator"))
node_flash[("Robot flash memory")]
node_bluetooth_module["Bluetooth module"]

node_user -->|"starts and configures"| node_main
node_main -->|"initializes board"| node_setup
node_main -->|"reads choices"| node_hmi
node_main -->|"explores and runs"| node_search
node_main -->|"configures control"| node_motion
node_main -->|"loads and saves maze"| node_maze_store
node_main -->|"checks voltage"| node_battery
node_setup -.->|"configures emitters"| node_sensing
node_setup -.->|"configures PWM"| node_motor_driver
node_maze_store -.->|"reads and writes"| node_flash
node_bluetooth_tool -->|"imports"| node_analysis
node_bluetooth_tool -.->|"communicates with"| node_bluetooth_module
node_bluetooth -.->|"sends and receives"| node_bluetooth_module
node_simulation_client -.->|"uses simulator"| node_simulation

click node_main "https://github.com/bulebots/bulebule/blob/master/src/main.c"
click node_search "https://github.com/bulebots/bulebule/tree/master/src/mmlib"
click node_motion "https://github.com/bulebots/bulebule/tree/master/src/mmlib"
click node_hmi "https://github.com/bulebots/bulebule/tree/master/src/mmlib"
click node_maze_store "https://github.com/bulebots/bulebule/blob/master/src/eeprom.c"
click node_setup "https://github.com/bulebots/bulebule/blob/master/src/setup.c"
click node_sensing "https://github.com/bulebots/bulebule/blob/master/src/detection.c"
click node_motor_driver "https://github.com/bulebots/bulebule/blob/master/src/motor.c"
click node_battery "https://github.com/bulebots/bulebule/blob/master/src/voltage.c"
click node_bluetooth "https://github.com/bulebots/bulebule/blob/master/src/serial.c"
click node_bluetooth_tool "https://github.com/bulebots/bulebule/blob/master/scripts/connect_bluetooth.py"
click node_analysis "https://github.com/bulebots/bulebule/blob/master/scripts/analysis.py"
click node_simulation "https://github.com/bulebots/bulebule/blob/master/src/simulation/move.c"
click node_simulation_client "https://github.com/bulebots/bulebule/blob/master/scripts/simulation_client.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_search,node_motion,node_hmi,node_maze_store,node_simulation toneBlue
class node_setup,node_sensing,node_motor_driver,node_battery,node_flash toneAmber
class node_bluetooth,node_bluetooth_tool,node_analysis,node_simulation_client toneMint
class node_user,node_bluetooth_module toneIndigo
```

## Components

### Robot workflow

- [Firmware orchestration](https://github.com/bulebots/bulebule/blob/master/src/main.c): `src/main.c`
- [Maze exploration and run](https://github.com/bulebots/bulebule/tree/master/src/mmlib): `src/mmlib`
- [Motion and motor control](https://github.com/bulebots/bulebule/tree/master/src/mmlib): `src/mmlib`
- [Buttons and interface](https://github.com/bulebots/bulebule/tree/master/src/mmlib): `src/mmlib`
- [Saved maze storage](https://github.com/bulebots/bulebule/blob/master/src/eeprom.c): `src/eeprom.c`
- [Simulation movement](https://github.com/bulebots/bulebule/blob/master/src/simulation/move.c): `src/simulation/move.c`

### Robot hardware

- [Board initialization](https://github.com/bulebots/bulebule/blob/master/src/setup.c): `src/setup.c`
- [Infrared sensing](https://github.com/bulebots/bulebule/blob/master/src/detection.c): `src/detection.c`
- [Motor driver](https://github.com/bulebots/bulebule/blob/master/src/motor.c): `src/motor.c`
- [Battery monitoring](https://github.com/bulebots/bulebule/blob/master/src/voltage.c): `src/voltage.c`

### Connectivity and analysis

- [Bluetooth serial](https://github.com/bulebots/bulebule/blob/master/src/serial.c): `src/serial.c`
- [Bluetooth client](https://github.com/bulebots/bulebule/blob/master/scripts/connect_bluetooth.py): `scripts/connect_bluetooth.py`
- [Log analysis](https://github.com/bulebots/bulebule/blob/master/scripts/analysis.py): `scripts/analysis.py`
- [Simulation client](https://github.com/bulebots/bulebule/blob/master/scripts/simulation_client.c): `scripts/simulation_client.c`

### Other components

- **Robot operator**
- **Robot flash memory**
- **Bluetooth module**

## Connections

- Robot operator → Firmware orchestration: starts and configures (evidence: `src/main.c`)
- Firmware orchestration → Board initialization: initializes board (evidence: `src/main.c`)
- Firmware orchestration → Buttons and interface: reads choices (evidence: `src/main.c`)
- Firmware orchestration → Maze exploration and run: explores and runs (evidence: `src/main.c`)
- Firmware orchestration → Motion and motor control: configures control (evidence: `src/main.c`)
- Firmware orchestration → Saved maze storage: loads and saves maze (evidence: `src/main.c`)
- Firmware orchestration → Battery monitoring: checks voltage (evidence: `src/main.c`)
- Board initialization → Infrared sensing: configures emitters
- Board initialization → Motor driver: configures PWM
- Saved maze storage → Robot flash memory: reads and writes
- Bluetooth client → Log analysis: imports (evidence: `scripts/connect_bluetooth.py`)
- Bluetooth client → Bluetooth module: communicates with
- Bluetooth serial → Bluetooth module: sends and receives
- Simulation client → Simulation movement: uses simulator
