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.

---

Method 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. Download the firmware.ino.uf2 file from the release page.
2. Put the board into bootloader mode: Unplug the device.
3. Press and hold the BOOT button.
4. While holding the button, plug the device back in to your computer.
5. Release the BOOT button.
6. Drag and drop the firmware.ino.uf2 file onto the removable device labeled RPI-RP2.

[STEP 2 & 3]                                [STEP 4 & 5]
   +-----------------+                         +--------------------+
   |   BOOT BUTTON   |                         | USB TYPE-C CABLE   |
   +-----------------+                         +--------------------+
            |                                            |
            v                                            v
     Keep Pressed --------------------------------> Plug Device Back In
                                                         |
  [STEP 5: RELEASE]                                      v
  Release BOOT Button                                Board Mounts As
                                                      'RPI-RP2' Drive!

• Full Changelog: https://github.com/Pwnsat/FlatSat_Firmware/commits/v1.0.0

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.

Method 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

1. Download and install the latest Arduino IDE (v2.x or higher).
2. Open Arduino IDE and navigate to File -> Preferences (or Arduino IDE -> Settings on macOS).
3. Click OK.
4. Go to the left sidebar, click on the Boards Manager icon, search for Raspberry Pi Pico/RP2040, and click Install.

2. Clone the Repository

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

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:

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

4. Compilation & Upload Pipeline

1. In Arduino IDE, open the primary sketch file: FlatSat_Firmware.ino.
2. Connect your FlatSat hardware using the Physical Button Method described in Part 1 to ensure it's in bootloader mode (RPI-RP2 visible).
3. Select your board configuration from Tools -> Board -> Raspberry Pi Pico.
4. Click the Upload button (the arrow icon in the top left corner).
5. Arduino IDE will compile the code from source, automatically target the dual-core memory mapping, and flash the hardware over the virtual serial port.

5. Local Hardware Sanity Verification

Before conducting radio over-the-air tests, confirm that the system is booting successfully by monitoring the isolated debug data stream managed entirely by Core 1 over the USB interface.

1. Open your terminal and connect to the emulated USB Serial Line interface at a baud rate configuration of 115200:

From a macOS Terminal:

screen /dev/tty.usbmodem* 115200
(To exit the screen session in Mac, press Ctrl + A followed immediately by Ctrl + \).

From a Linux Terminal:

minicom -D /dev/ttyACM0 -b 115200

2. Expected Output Logs: Upon connection, you should witness automated diagnostic outputs tracking system execution tasks:

[INFO] USB Device configured successfully
[INFO] ACC OK
[INFO] BME OK
[INFO] Radio 0 Configured Successfully!
[INFO] Radio 1 Configured Successfully!
[TM - SPP] APID=0x008 SEQ=1 LEN=20 FLAGS=3 SEC_HDR=NO
[TM - SPP] APID=0x001 SEQ=2 LEN=8 FLAGS=3 SEC_HDR=NO
[TM - SPP] APID=0x3FF SEQ=0 LEN=14 FLAGS=3 SEC_HDR=NO

If you see these telemetry outputs updating regularly, your processing hardware, primary sensor buses, and operating software runtime are completely functional.

Time to test: RF Telemetry Interception & Verification

FlatSat acts as a live, functional satellite simulator broadcasting true CCSDS packets into local airspace using sub-GHz radio modulations. You can physically confirm over-the-air operations using passive and analytical Software Defined Radios (SDR).

Local Hardware Sanity Check

Before performing radio tests, ensure the board is running properly by opening the Serial Monitor in Arduino IDE (configured to 115200 baud). You should see automated diagnostic outputs tracking system execution tasks: