Getting Started

FlatSat Firmware: Getting Started, Compilation & Testing

This comprehensive guide covers the end-to-end process of setting up, flashing, and validating your FlatSat environment. Whether you want to quickly flash a pre-compiled release or compile everything from source across different operating systems, follow the steps below.

---

Part 1: Quick Start - Flashing Pre-Compiled Firmware

If you do not need to modify the source code and want to get your FlatSat board running immediately, you can flash the pre-compiled production binary.

1. Download the Firmware Binary

Download the latest .uf2 file from our repository releases page:

• Production Firmware URL: https://github.com/Pwnsat/FlatSat_Firmware/releases (Locate and download flatsat_firmware.uf2)

2. Hardware Flashing Sequence (Physical Button Method)

The FlatSat board features an on-board USB Mass Storage bootloader hardcoded into the RP2040 chip. You do not need external hardware debuggers to write the firmware.

Follow this exact tactile switch sequence:

1. Locate the two micro-switches labeled BOOT (Bootloader) and RST (Reset) on the FlatSat board.
2. Connect the FlatSat board to your computer using a high-quality USB Type-C data cable.
3. Press and hold down the BOOT button. (Do not release it yet).
4. While keeping the BOOT button fully depressed, press and release the RST button once.
5. Keep holding the BOOT button down for exactly one additional second, then release it.

  [STEP 3: HOLD DOWN]                        [STEP 4: PRESS & RELEASE]
   +-----------------+                          +-----------------+
   |   BOOT BUTTON   |                          |   RST BUTTON    |
   +-----------------+                          +-----------------+
            |                                            |
            v                                            v
     Keep Pressed --------------------------------> Press & Release Once
                                                         |
  [STEP 5: RELEASE]                                      v
  Release BOOT after 1 sec                           Board Resets Into
                                                      Bootloader Mode!

3. Deploying the File

1. Your operating system will instantly detect the device as a standard USB thumb drive volume named RPI-RP2.
2. Drag and drop or copy the downloaded flatsat_firmware.uf2 file directly into the root directory of the mounted RPI-RP2 drive.
3. As soon as the transfer completes, the FlatSat hardware will automatically unmount, flash its internal memory, reset, and immediately begin running the satellite flight software.

Part 2: Advanced Start - Compiling & Flashing via Arduino IDE

If you want to modify, compile, and upload the source code manually, follow these standard Arduino IDE instructions tailored for Windows, macOS, and Linux.

1. IDE Setup & Board Manager Installation Download and install the latest Arduino IDE (v2.x or higher).

Open Arduino IDE and navigate to File -> Preferences (or Arduino IDE -> Settings on macOS).

In the Additional Boards Manager URLs field, paste the following URL: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json

Click OK.

Go to the left sidebar, click on the Boards Manager icon, search for Raspberry Pi Pico/RP2040, and click Install.

2. Clone the Repository Open your terminal or command prompt and clone the workspace recursively to include all underlying aerospace submodules:

Bash git clone --recursive https://github.com/Pwnsat/FlatSat_Firmware.git 3. OS-Specific Prerequisites & Configurations

Windows Port Detection: Ensure you have the official Raspberry Pi drivers installed (automatically bundled with the Arduino Pico core).

Target Configurations: In Arduino IDE, go to Tools -> Board -> Raspberry Pi Pico/RP2040 and select Raspberry Pi Pico.

MacOS Permissions: macOS might require security authorization for compilation toolchains. If prompted with a developer verification block under System Settings -> Privacy & Security, click Allow Anyway.

Target Configurations: Select Raspberry Pi Pico under the RP2040 boards menu.

Linux (Debian / Ubuntu / Kali) Dialout Permissions: To read and write to USB serial ports without root permissions, add your user to the dialout group:

Bash sudo usermod -aG dialout $USER (Log out and log back in for changes to take effect).

4. Compilation & Upload Pipeline In Arduino IDE, open the primary sketch file: FlatSat_Firmware.ino.

Connect your FlatSat hardware using the Physical Button Method described in Part 1 to ensure it's in bootloader mode (RPI-RP2 visible).

Select your board configuration from Tools -> Board -> Raspberry Pi Pico.

Click the Upload button (the arrow icon in the top left corner).

Arduino IDE will compile the code from source, automatically target the dual-core memory mapping, and flash the hardware over the virtual serial port.