Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
9bb3dceeaThis file is pinned to the selected release. Download the original to open it in your design tool.
# Tinymovr Directory Structure
**Purpose**: Quick reference to project organization and file locations.
**Target Audience**: Developers and AI agents navigating the codebase.
## Repository Organization
```
Tinymovr/
├── firmware/ # Embedded C firmware for PAC5527 MCU
├── studio/ # Python client library and tools
├── hardware/ # Hardware design files and datasheets
├── docs/ # Sphinx documentation (user-facing)
├── avlos_config.yaml # Code generation configuration
├── ARCHITECTURE.md # System architecture guide
├── SAFETY.md # Safety-critical constraints
├── AVLOS_GUIDE.md # Protocol modification guide
├── CONVENTIONS.md # Code style and patterns
├── TESTING.md # Testing practices
├── CLAUDE.md # AI agent navigation
├── CONTRIBUTING.md # Contribution workflow
└── README.md # Project overview
```
## Firmware Structure
### Top Level
```
firmware/
├── src/ # Source code (17 modules)
├── pac55xx_sdk/ # Qorvo PAC55xx SDK (not in repo)
├── pac55xx_device_pack/ # CMSIS Device Family Pack for PyOCD/J-Link
├── bootloader/ # CAN/DFU bootloader source
├── build/ # Build artifacts (.elf, .bin, .map)
├── release_binaries/ # Pre-built release binaries
├── scripts/ # Utility scripts for flashing/debugging
│ ├── pyocd_run.sh # PyOCD wrapper (discovers venv or PATH)
│ └── pyocd_run.bat # Windows version
├── Makefile # Build system
├── pac55xx.ld # Linker script (memory layout)
└── sdk_patch.patch # SDK modifications
```
### Scripts Directory
The ``firmware/scripts/`` directory contains utility scripts for flashing and debugging:
| Script | Purpose |
|--------|---------|
| `pyocd_run.sh` | Wrapper script that finds PyOCD in PATH or project venv. **Required** because Makefile commands spawn a new shell without access to any activated virtual environment. |
| `pyocd_run.bat` | Windows equivalent of pyocd_run.sh |
### Source Modules
```
firmware/src/
├── main.c # Entry point, initialization
├── common.h # Board revisions, global includes
├── config.h # System constants, timing parameters
├── tm_enums.h # Generated enums (from Avlos)
│
├── controller/ # FOC control loops
│ ├── controller.c # Main control loop (20 kHz)
│ └── controller.h # Control state and configuration
│
├── motor/ # Motor management and calibration
│ ├── motor.c # Calibration sequences (R, L, poles)
│ └── motor.h # Motor parameters, limits
│
├── observer/ # State estimation
│ ├── observer.c # Position/velocity estimation
│ └── observer.h # Observer state
│
├── sensor/ # Encoder drivers
│ ├── sensors.c # Sensor abstraction layer
│ ├── ma7xx.c # MPS MA7xx (onboard)
│ ├── as5047.c # AMS AS5047 (external SPI)
│ ├── amt22.c # CUI AMT22 (external SPI)
│ └── hall.c # Hall effect sensors
│
├── gatedriver/ # PWM generation
│ ├── gatedriver.c # Space Vector Modulation (SVM)
│ └── gatedriver.h # PWM configuration
│
├── adc/ # Current sensing
│ ├── adc.c # ADC initialization, ISR
│ └── adc.h # ADC channels, calibration
│
├── can/ # CAN bus communication
│ ├── can.c # CAN driver, message handling
│ ├── can.h # CAN configuration
│ ├── can_endpoints.c # Generated Avlos endpoints
│ └── can_endpoints.h # Generated Avlos declarations
│
├── uart/ # UART communication (alternative)
│ ├── uart.c # UART driver
│ └── uart.h # UART configuration
│
├── ssp/ # SPI/SSP peripheral
│ ├── ssp.c # SPI driver for external encoders
│ └── ssp.h # SPI configuration
│
├── nvm/ # Non-volatile memory (flash)
│ ├── nvm.c # Configuration persistence
│ └── nvm.h # NVM structure
│
├── system/ # Platform-level services
│ ├── system.c # Clock config, reset, voltage monitoring
│ └── system.h # System state
│
├── scheduler/ # Timing and synchronization
│ ├── scheduler.c # Control loop synchronization
│ └── scheduler.h # Scheduler state, load monitoring
│
├── watchdog/ # Communication timeout
│ ├── watchdog.c # Watchdog timer management
│ └── watchdog.h # Watchdog configuration
│
├── timer/ # Hardware timers
│ ├── timer.c # PWM timer setup
│ └── timer.h # Timer configuration
│
├── utils/ # Math utilities
│ ├── utils.c # Fast trig, SVM algorithm
│ └── utils.h # Utility functions
│
└── rtt/ # SEGGER RTT debug output
├── SEGGER_RTT.c # RTT implementation
└── SEGGER_RTT.h # RTT interface
```
### Key Firmware Files
| File | Purpose |
|------|---------|
| [firmware/src/main.c](firmware/src/main.c) | Entry point, startup sequence |
| [firmware/src/common.h](firmware/src/common.h) | Board revision defines, includes |
| [firmware/src/config.h](firmware/src/config.h) | Timing, PWM frequency, limits |
| [firmware/src/controller/controller.c](firmware/src/controller/controller.c) | Main control loop (20 kHz) |
| [firmware/src/motor/motor.c](firmware/src/motor/motor.c) | Calibration implementation |
| [firmware/src/motor/motor.h](firmware/src/motor/motor.h) | Calibration constants, motor limits |
| [firmware/src/can/can_endpoints.c](firmware/src/can/can_endpoints.c) | Generated Avlos endpoints (97 endpoints) |
| [firmware/src/tm_enums.h](firmware/src/tm_enums.h) | Generated enums (states, errors, options) |
| [firmware/Makefile](firmware/Makefile) | Build system (REV=R52, debug/release) |
| [firmware/pac55xx.ld](firmware/pac55xx.ld) | Memory layout (128KB flash, 32KB RAM) |
## Studio Structure
### Top Level
```
studio/Python/
├── tinymovr/ # Main package
├── tests/ # Test suite (HITL and simulation)
├── scripts/ # Utility scripts
├── setup.py # Package installation
└── package.json # Node.js dependencies (GUI)
```
### Package Structure
```
studio/Python/tinymovr/
├── __init__.py # Package initialization
├── __main__.py # CLI entry point
│
├── specs/ # YAML API specifications (Avlos)
│ ├── tinymovr_1_3_x.yaml
│ ├── tinymovr_2_0_x.yaml
│ ├── tinymovr_2_1_x.yaml
│ ├── tinymovr_2_2_x.yaml
│ └── tinymovr_2_3_x.yaml # Current version
│
├── config/ # Configuration and spec loading
│ ├── config.py # Spec loading, hash matching, device discovery
│ └── __init__.py
│
├── codec/ # Binary serialization
│ ├── codec.py # Multibyte codec for CAN messages
│ └── __init__.py
│
├── bus_router.py # Global singleton, message distribution
├── bus_manager.py # CAN bus connection, auto-reconnect
├── channel.py # Per-device communication channel
├── device_discovery.py # Automatic device detection via heartbeat
├── constants.py # Constants (node IDs, timeouts)
│
├── gui/ # Qt-based graphical interface
│ ├── main.py # GUI entry point
│ ├── widgets/ # Custom widgets
│ └── resources/ # Icons, stylesheets
│
└── resources/ # Package resources
└── schema.json # JSON schema for validation
```
### Test Structure
```
studio/Python/tests/
├── tm_test_case.py # Base class for HITL tests
├── test_simulation.py # Simulation tests (no hardware)
├── test_board.py # Core HITL tests
├── test_sensors.py # Sensor-specific tests
├── test_homing.py # Homing feature tests
├── test_trajectory.py # Trajectory planner tests
└── test_eol.py # End-of-line comprehensive tests
```
### Key Studio Files
| File | Purpose |
|------|---------|
| [studio/Python/tinymovr/specs/tinymovr_2_3_x.yaml](studio/Python/tinymovr/specs/tinymovr_2_3_x.yaml) | Current API specification |
| [studio/Python/tinymovr/config/config.py](studio/Python/tinymovr/config/config.py) | Spec loading and hash matching |
| [studio/Python/tinymovr/bus_router.py](studio/Python/tinymovr/bus_router.py) | Message routing singleton |
| [studio/Python/tinymovr/channel.py](studio/Python/tinymovr/channel.py) | Per-device CAN channel |
| [studio/Python/tests/tm_test_case.py](studio/Python/tests/tm_test_case.py) | Base class for HITL tests |
| [studio/Python/setup.py](studio/Python/setup.py) | Package installation config |
## Hardware Structure
```
hardware/
├── R5/ # R5.x series boards (high-current)
│ ├── R50/ # R5.0 design files
│ ├── R51/ # R5.1 design files
│ ├── R52/ # R5.2 design files
│ └── R53/ # R5.3 design files
│
├── M5/ # M5.x series boards (gimbal)
│ └── M51/ # M5.1 design files
│
├── R3/ # R3.x series boards (legacy)
│ ├── R32/ # R3.2 design files
│ └── R33/ # R3.3 design files
│
├── Actuator/ # Complete actuator designs
├── ServoKit/ # Development/testing hardware
├── Datasheets/ # MCU and component datasheets
│ ├── PAC5527 Data Sheet.pdf
│ └── UG_PAC5527.pdf
│
└── misc/ # Miscellaneous hardware files
```
## Documentation Structure
```
docs/
├── index.rst # Documentation home
├── conf.py # Sphinx configuration
│
├── hardware/ # Hardware documentation
│ ├── board_versions.rst
│ └── specifications.rst
│
├── control/ # Control theory and tuning
│ ├── position_control.rst
│ ├── velocity_control.rst
│ └── current_control.rst
│
├── features/ # Feature guides
│ ├── calibration.rst
│ ├── homing.rst
│ └── trajectory.rst
│
├── protocol/ # Communication protocol
│ ├── overview.rst
│ └── reference.rst # Generated from Avlos
│
├── studio/ # Python client usage
│ ├── installation.rst
│ └── quickstart.rst
│
├── develop/ # Developer guides
│ ├── firmware.rst
│ └── python.rst
│
└── interfaces/ # Interface guides
├── can.rst
└── uart.rst
```
## Code Generation Files
| File | Purpose |
|------|---------|
| [avlos_config.yaml](avlos_config.yaml) | Avlos code generation configuration |
| [studio/Python/tinymovr/specs/tinymovr_2_3_x.yaml](studio/Python/tinymovr/specs/tinymovr_2_3_x.yaml) | API specification (input) |
| [firmware/src/can/can_endpoints.c](firmware/src/can/can_endpoints.c) | Generated C implementation |
| [firmware/src/can/can_endpoints.h](firmware/src/can/can_endpoints.h) | Generated C header |
| [firmware/src/tm_enums.h](firmware/src/tm_enums.h) | Generated enums |
| [docs/protocol/reference.rst](docs/protocol/reference.rst) | Generated documentation |
**Workflow**:
```bash
avlos from file <spec_file>.yaml
```
## Build Artifacts
### Firmware Build
```
firmware/build/
├── tinymovr_fw.elf # Executable with debug symbols
├── tinymovr_fw.bin # Binary for flashing
├── tinymovr_fw.map # Memory map
└── *.o # Object files
```
### Python Build
```
studio/Python/
├── dist/ # Wheel and source distribution
│ ├── tinymovr-X.Y.Z-py3-none-any.whl
│ └── tinymovr-X.Y.Z.tar.gz
└── tinymovr.egg-info/ # Package metadata
```
## Ignored Directories
Not tracked in version control (see `.gitignore`):
```
firmware/pac55xx_sdk/ # PAC55xx SDK (copyright restrictions)
firmware/build/ # Build artifacts
studio/Python/dist/ # Python distribution packages
studio/Python/*.egg-info/ # Python package metadata
venv/ # Python virtual environment
docs/_build/ # Sphinx build output
__pycache__/ # Python bytecode cache
.vscode/ # Editor settings
.DS_Store # macOS metadata
```
## Quick Navigation by Task
### Modifying Control Loop
- Start: [firmware/src/controller/controller.c](firmware/src/controller/controller.c)
- Check: [SAFETY.md](SAFETY.md) for constraints
### Adding API Endpoint
- Edit: [studio/Python/tinymovr/specs/tinymovr_2_3_x.yaml](studio/Python/tinymovr/specs/tinymovr_2_3_x.yaml)
- Generate: `avlos from file <spec_file>.yaml`
- Implement: Appropriate module in `firmware/src/`
### Modifying Calibration
- Edit: [firmware/src/motor/motor.c](firmware/src/motor/motor.c)
- Check: [firmware/src/motor/motor.h](firmware/src/motor/motor.h) for constants
### Writing Tests
- HITL: [studio/Python/tests/test_board.py](studio/Python/tests/test_board.py)
- Simulation: [studio/Python/tests/test_simulation.py](studio/Python/tests/test_simulation.py)
- Base class: [studio/Python/tests/tm_test_case.py](studio/Python/tests/tm_test_case.py)
### Adding Board Revision
- Edit: [firmware/src/common.h](firmware/src/common.h)
- Update: [firmware/Makefile](firmware/Makefile)
## References
- [ARCHITECTURE.md](ARCHITECTURE.md) - System design and module responsibilities
- [CONVENTIONS.md](CONVENTIONS.md) - Code style and patterns
- [AVLOS_GUIDE.md](AVLOS_GUIDE.md) - Protocol modification workflow
- [TESTING.md](TESTING.md) - Testing practices
---
**Document Status**: Living document, updated as project structure evolves.