commit 6459fe2f0266956ef908aed4598f75497d27cedd
Author: Dejvino <dejvino@gmail.com>
Date:   Mon Feb 23 22:28:30 2026 +0100

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..753ace4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# Raspberry Pi 1 Bare-Metal Synthesizer
+
+This project turns an original Raspberry Pi (Model 1 B/B+, Zero, or Zero W) into an instant-on, single-voice synthesizer that runs without any operating system (bare metal).
+
+It boots in under two seconds and produces sound and graphics with minimal external components.
+
+## Features
+
+- **Instant-On**: Boots directly into the synth application in ~1-2 seconds.
+- **Audio Output**: Generates a sawtooth waveform on the 3.5mm composite audio jack.
+- **Video Output**: Displays a simple amplitude visualizer on the composite video output.
+- **Looped Melody**: Plays a pre-programmed random melody, no input required.
+
+## Requirements
+
+### Hardware
+
+- **Raspberry Pi**: Model 1 (A, B, B+), Pi Zero, or Pi Zero W. This code is for the **BCM2835** SoC and will **not** work on Pi 2, 3, 4, or 5.
+- **SD Card**: A microSD or standard SD card (depending on your Pi model), 1GB is more than enough.
+- **Power Supply**: A standard 5V micro-USB power supply.
+- **Audio Cable**: A 3.5mm audio cable to connect to headphones or a speaker.
+
+### Software
+
+- **ARM Cross-Compiler**: The `arm-none-eabi-gcc` toolchain is required to build the kernel.
+- **Raspberry Pi Firmware**: You need the `bootcode.bin` and `start.elf` files from the official Raspberry Pi firmware repository.
+
+## Quick Start with Scripts
+
+For a fast and easy setup, you can use the provided automation scripts.
+
+1.  **Build the kernel**:
+    ```sh
+    ./build.sh
+    ```
+    This will compile the C and Assembly code and create the `kernel.img` file.
+
+2.  **Deploy to SD Card**:
+    Insert your FAT32-formatted SD card. Find its device name (e.g., `/dev/sdX` or `/dev/mmcblkX`) and mount point.
+
+    ```sh
+    # Example: ./deploy.sh /media/user/RASPIBOOT
+    ./deploy.sh <path_to_sd_card_mount_point>
+    ```
+    This script copies `kernel.img`, `bootcode.bin`, and `start.elf` to the SD card and then safely unmounts it.
+
+## Manual Setup and Deployment
+
+### 1. Install Toolchain
+
+On Debian/Ubuntu-based systems, you can install the cross-compiler with:
+```sh
+sudo apt-get update
+sudo apt-get install gcc-arm-none-eabi binutils-arm-none-eabi
+```
+
+### 2. Get Raspberry Pi Firmware
+
+The Pi's GPU first loads firmware from the SD card before handing control to the ARM core. You need two files:
+
+- `bootcode.bin`: The second-stage bootloader.
+- `start.elf`: The GPU firmware.
+
+You can download them from the official Raspberry Pi firmware repository. Make sure to grab the files from the `boot` directory. For this project, you only need these two files.
+
+Place them in the root of this project directory so the `deploy.sh` script can find them.
+
+### 3. Build the Kernel
+
+With the toolchain installed, compile the synthesizer by running `make`:
+```sh
+make
+```
+This command uses the `Makefile` to compile `boot.S` and `kernel.c`, linking them into a final binary image named `kernel.img`.
+
+### 4. Prepare the SD Card
+
+Your SD card must be formatted with a **FAT32** filesystem. Most new SD cards are already formatted this way. The partition should also have the "boot" or "lba" flag set, which is standard for bootable Raspberry Pi cards.
+
+### 5. Deploy to SD Card
+
+Mount the SD card and copy the three essential files to its root directory:
+
+- `bootcode.bin` (from the firmware repo)
+- `start.elf` (from the firmware repo)
+- `kernel.img` (generated by the `make` command)
+
+After copying, unmount the SD card safely.
+
+## Hardware Connections
+
+1.  **SD Card**: Insert the prepared SD card into your Raspberry Pi.
+2.  **Audio**: Connect headphones or a speaker to the 3.5mm audio jack.
+3.  **Video (Optional)**: Connect a composite video cable from the RCA jack (on Model B) or the 3.5mm jack (on later models) to a compatible display.
+4.  **Power**: Connect the 5V micro-USB power supply. The Pi will boot immediately.
+
+## Usage
+
+Once powered on, the synthesizer will automatically start playing a random melody loop. The composite video output will show a simple red bar that visualizes the audio amplitude.
+
+There is no user input required for this version of the code.
+
+---
+
+*This project is for educational purposes and demonstrates low-level hardware control on the BCM2835 SoC.*
\ No newline at end of file