Merge pull request #52 from alvarolobato/headless

Document headless build and update screenshot docs

Author: fvanroie

docs/commands.md

@@ -285,7 +285,7 @@ This can be handy for bug reporting or documentation.
 
 The previous screenshot is overwritten.
 
-On the **Mac desktop build**, the screenshot is saved as `screenshot.bmp` in the working directory. You can optionally pass a custom file path as a parameter. Press **F12** in the simulator window as a shortcut.
+On the **desktop builds** (Mac, Linux, and headless), the screenshot is saved as `screenshot.bmp` in the working directory. You can optionally pass a custom file path as a parameter. Press **F12** in the simulator window as a shortcut (windowed builds only).
 
 ### `service`
 

docs/commands/system.md

@@ -45,10 +45,13 @@ This can be handy for bug reporting or documentation.
 
 The previous screenshot is overwritten.
 
-On the **Mac desktop build**, the screenshot is saved as `screenshot.bmp` in the working directory. You can optionally pass a custom file path as a parameter.
+On the **desktop builds** (Mac, Linux, and headless), the screenshot is saved as `screenshot.bmp` in the working directory. You can optionally pass a custom file path as a parameter.
 
 !!! tip
-    Press **F12** in the simulator window to take a screenshot without using MQTT.
+    Press **F12** in the simulator window to take a screenshot without using MQTT (windowed builds only).
+
+!!! note "Headless build"
+    The `linux_headless` build supports screenshots via MQTT without any display server or SDL2 dependency. This makes it suitable for CI/CD pipelines, Docker containers, and headless servers.
 
 ## `service`
 

docs/firmware/compiling/local.md

@@ -90,12 +90,37 @@ You can now run "Build" or "Build All" in PlatformIO to compile (all) the firmwa
 
 ### Native Linux build
 
-For native linux_sdl builds, you also need:
+For native `linux_sdl` builds (with GUI window), you also need:
 ```
 sudo apt update
 sudo apt install build-essential libsdl2-dev
 ```
 
+### Headless Linux build
+
+The `linux_headless` build runs without any display server or SDL2 dependency. It uses a null display driver with an in-memory framebuffer, making it ideal for CI/CD pipelines, Docker containers, and headless servers. Screenshots are captured via MQTT.
+
+No extra system packages are needed beyond a C++ compiler:
+```
+sudo apt update
+sudo apt install build-essential
+```
+
+Uncomment `user_setups/linux/*.ini` in your `platformio_override.ini`, then:
+```
+pio run -e linux_headless
+```
+
+Run the headless binary:
+```
+./program -c /path/to/config
+```
+
+Take a screenshot via MQTT:
+```
+mosquitto_pub -t "hasp/<plate>/command/screenshot" -m "/path/to/screenshot.bmp"
+```
+
 
 ### Native MacOS build