lezyne-rear-light-firmware/README.md

# lezyne-rear-light-firmware

**🚧 Work in progress. No complete firmware yet 🚧**

🚀 For pre-build binaries go to [Releases](https://git.mosad.xyz/localhorst/lezyne-rear-light-firmware/releases).

Open firmware for Lezyne bike rear lights based on ATTINY202

This repository contains a minimal firmware as a **C project** for the ATtiny202 microcontroller using **GCC**, **CMake**, and **VS Code**. It also includes instructions for programming the chip using an **FT232 USB-UART adapter** via the UPDI interface with `pymcuprog`.  

---

## Table of Contents

- [Dependencies](#dependencies)
- [Setup Build Environment](#setup-build-environment)
- [Building the Project](#building-the-project)
- [Flashing the Firmware](#flashing-the-firmware)
- [Reading Flash Content](#reading-flash-content)
- [Hardware Setup](#hardware-setup)
- [License](#license)

---

## Dependencies

Ensure the following tools are installed on your system:

- **GCC AVR toolchain** (supports ATtiny 0/1-series)  
  ```bash
  sudo zypper install avr-gcc avr-libc
    ```
- **CMake**
  ```bash
    sudo zypper install cmake
    ```
- **Python 3, pip and venv**
  ```bash
    sudo zypper install python3 python3-pip python3-venv
    ```
- **VS Code** (optional but recommended)
- **CMake Tools extension** for VS Code

## Setup Build Environment
1. Clone the repository:
   ```bash
    git clone https://git.mosad.xyz/localhorst/lezyne-rear-light-firmware
    cd lezyne-rear-light-firmware
    ```
2. Configure the CMake project:
    - Open the folder in VS Code.
    - Select the AVR-GCC kit in the bottom blue bar.
    - Run CMake: Configure (from command palette) if it doesn't auto-run.

## Building the Project
1. Press F7 or Ctrl+Shift+B to build.
2. Output files are generated in the 'build/' folder:
- main.elf → ELF executable
- main.hex → HEX file (flashable)
- main.bin → BIN file

## Flashing the Firmware
Hardware: FT232 USB-UART adapter connected to UPDI with a 4.7 kΩ resistor.
1. Create and activate a Python virtual environment:
   ```bash
    python3 -m venv pyupdi-env
    source pyupdi-env/bin/activate
    ```
2. Install pymcuprog inside the environment:
   ```bash
    pip install pymcuprog
   ```
3. Verify installation:
   ```bash
    pymcuprog --version
   ```
4. Flash using pymcuprog:
   ```bash
    pymcuprog -t uart -u /dev/ttyUSB0 -d attiny202 write -f build/main.hex
   ```
## Hardware Setup (FT232 → ATtiny202 UPDI)
   ```bash
    FT232 TX ----[4.7kΩ]---- UPDI (Pin 6)
    FT232 GND --------------- GND
    VCC -------------------- VCC (3.3V or 5V, must match FT232 logic)
   ```
*Hint:* The GPIO PA0 acts as UPDI of ATtiny202 and needs to be disconnected from the PCB during programming. 

## ATtiny202-SSN Pin Mapping (PCB Usage)
![Image of the PCB in doc/ folder.](doc/bottom_side.png "Back of PCB")
![Image of the PCB in doc/ folder.](doc/front_side.png "Front of PCB")

| Pin # | Pin Name | Port | PCB Usage                | Direction                                |
|------:|----------|------|--------------------------|------------------------------------------|
|     1 | VDD      | —    | +VDD (Power)             | Power Input                              |
|     2 | PA6      | IO   | Green LED                | Output                                   |
|     3 | PA7      | IO   | Red LED                  | Output                                   |
|     4 | PA1      | IO   | LED 1–2                  | Output                                   |
|     5 | PA2      | IO   | LED 3–6                  | Output                                   |
|     6 | PA3      | IO   | LED 7–8                  | Output                                   |
|     7 | PA0      | IO   | UPDI / Activation Button | Input (button, pull-up) / UPDI (program) |
|     8 | GND      | —    | Ground                   | Power Ground                             |

---

### Logic Levels (LEDs & Button)

| Signal | PCB Usage         | LOW                      | HIGH                      |
|--------|-------------------|--------------------------|---------------------------|
| PA6    | Green LED         | LED **ON**               | LED **OFF**               |
| PA7    | Red LED           | LED **ON**               | LED **OFF**               |
| PA1    | LED 1–2           | LED(s) **OFF**           | LED(s) **ON**             |
| PA2    | LED 3–6           | LED(s) **OFF**           | LED(s) **ON**             |
| PA3    | LED 7–8           | LED(s) **OFF**           | LED(s) **ON**             |
| PA0    | Activation Button | Button **pressed** (GND) | Button released (pull-up) |

## License

This project is licensed under the MIT License. See [LICENSE](./LICENSE) for details.