Zephyr-Doom

Content

• 1. Introduction
• 2. Status
  • 2.1. Backlog
• 3. Getting Started
  • 3.1. HW Configuration Index
  • 3.2. SW Configuration Index
  • 3.3. Compatibility Matrix
  • 3.4. Prerequisites
  • 3.5. Build
  • 3.6. Flash
• 4. MVPs
  • 4.1. MVP1
  • 4.2. MVP2
  • 4.3. MVP3
  • 4.4. MVP4
  • 4.5. MVP5
• 5. Release Notes
  • 5.1. Fixed Bugs
  • 5.2. Known Bugs
  • 5.3. Implemented Improvements
  • 5.4. Known Limitations

1. Introduction

This is a port of Doom (1993) for Zephyr RTOS.

The project is forked from nrf-doom (commit 2d42413), which is forked from Chocolate Doom version 3.0.0.

The objective of this internship project is to develop a Zephyr port of the game, making sure it can run on different System-on-Chips (SoCs). This endeavor will be divided into several stages, presented as Minimum Viable Product (MVP) packages.

Zephyr-Doom has only been tested with Shareware version of Doom 1.

Game	Status	Comment
Doom 1 Shareware	OK	N/A
Doom 1 Full Version	Not Tested	N/A
Doom 2	Not Tested	N/A

2. Status

2.1. Backlog

Feature	Status	Comment
Game data in QSPI flash	Done	N/A
Doom game engine running	Done	N/A
Devkit button control	Done	N/A
GPIO ILI9486 display support	Done	Currently, there is a limitation on the FPS and the picture is rotated by 90°.
SPI ILI9341 display support	Done	FPS got significantly decreased due to the multiple HW/SW limitations.
SPI FT810 display support	Done	FPS matching nrf-doom performance.
BLE game controller	Done	Transition from the original proprietary radio protocol to BLE using the Nordic UART Service (NUS) for data exchange.
BLE HID support	In progress	Replace NUS communication with BLE HID standard to allow control via gamepad (test with Xbox wireless controller) and keyboard (test with BLE keyboard built on RPi 400).
Game data (SD card to flash)	In progress	Automatically copy game data from SD card to flash during first start (or on demand).
Game save and load	Open	Enable save and load functionality to store/restore gameplay progress.
Pure Zephyr port	Open	Modify the code to make it compatible with any Zephyr device that meets the resource requirements by removing NRFX/NCS elements.
Basic CI	In progress	Build the code for target platforms in GitHub actions.
Static analysis	Open	N/A
Simulation on PC	Open	Native Posix target.
Gamepad calibration	Open	N/A
Touchscreen controls	Open	Use dedicated area of display to control movement and fire.
Sound	Open	N/A
Multiplayer	Open	N/A
Music	Open	N/A

3. Getting Started

3.1. HW Configuration Index

Item	Version	Comment
nRF5340 dev kit	2.0.1	N/A
3,5" ILI9486 display	N/A	N/A
2,8" ILI9341 SPI display	N/A	N/A
4,3" FT810 SPI IPS display	N/A	N/A
micro:bit v2	2.x	N/A
joystick v2	2.x	N/A
Xbox controller	Model 1914	N/A
Keyboard	RPi 400	N/A

3.2. SW Configuration Index

Item	Version	Comment
Windows 11 Enterprise	10.0.22631	N/A
Visual Studio Code	1.98.2	N/A
nRF Connect SDK	v2.6.2	N/A
nRF Connect for Visual Studio Code	2025.1.127	Can be downloaded using the Toolchain Manager found in nRF Connect for Desktop. Alternatively, it can be downloaded directly from inside Visual Studio Code.

3.3. Compatibility Matrix

Legend
✅	Hardware supported.
❌	Hardware not supported.

Item	Version	MPV1	MVP2	MVP3	MVP4	MVP5
nRF5340 dev kit	2.0.1	✅	✅	✅	✅	✅
3,5" ILI9486 display	N/A	✅	✅	❌	❌	❌
2.8" ILI9341 SPI display	N/A	❌	❌	✅	❌	❌
4.3" SPI IPS display	N/A	❌	❌	❌	✅	✅
micro:bit v2	2.x	❌	✅	✅	✅	❌
joystick v2	2.x	❌	✅	✅	✅	❌
Xbox controller	Model 1914	❌	❌	❌	❌	✅
Keyboard	RPi 400	❌	❌	❌	❌	✅

3.4. Prerequisites

1. Install the Visual Studio Code.

2. Install the nRF Connect SDK.

3. Install the nRF Connect for VS Code.

3.5. Build

3.5.1. Game

• Visual Studio Code → nRF Connect extension → Add Folder as Application → Select zephyrdoom folder;

• Visual Studio Code → nRF Connect extension → Applications → Add build configuration → Select board target nrf5340dk_nrf5340_cpuapp → Build Configuration;

3.5.2. Gamepad

• Visual Studio Code → nRF Connect extension → Add Folder as Application → Select gamepad/microbit folder;

• Visual Studio Code → nRF Connect extension → Applications → Add build configuration → Select board target bbc_microbit_v2 → Build Configuration;

3.6. Flash

3.6.1. Game

1. Connect Nordic Semiconductor nRF5340 dev kit.

2. Flash data (contains WAD file) to external flash:

   nrfjprog --family nrf53 --qspicustominit --program qspi.hex --verify

3. Select game app.

   Visual Studio Code → nRF Connect extension → Applications → Select zephyrdoom;

4. Flash the game.

   Visual Studio Code → nRF Connect extension → Actions → Flash;

3.6.2. Gamepad

1. Connect micro:bit v2.

2. Select gamepad app.

   Visual Studio Code → nRF Connect extension → Applications → Select microbit;

3. Copy file gamepad/microbit/build/zephyr/zephyr.hex to micro:bit (acting as a removable USB device).

3.6.3. Monitor

1. Visual Studio Code → nRF Connect extension → Connected Devices → VCOM1 → Connect to Serial Port;

4. MVPs

4.1. MVP1

• Goals:

  • Port nrf-doom to nRF Connect SDK.

  • Get it up and running with display and basic control using dev kit buttons under Zephyr RTOS (still with dependency on nRF Connect SDK).

• Features:

  • QSPI flash;

  • Doom engine running;

  • Basic display support;

  • Nordic Semiconductor nRF5340 dev kit button control;

• Required Hardware:

  • Nordic Semiconductor nRF5340 dev kit;

  • 3,5" ILI9486 display without touch feature;

• Pins mapping:

  • Nordic Semiconductor nRF5340 dev kit:

    Peripheral	Function	nRF5340 Pin
    Buttons	Button 1	P0.23
    Buttons	Button 2	P0.24
    Buttons	Button 3	P0.8
    Buttons	Button 4	P0.9
    LEDs	LED 1	P0.28
    LEDs	LED 2	P0.29
    LEDs	LED 3	P0.30
    LEDs	LED 4	P0.31
    SPI/SD card	SS	P1.12
    SPI/SD card	DI	P1.13
    SPI/SD card	DO	P1.14
    SPI/SD card	SCK	P1.15
    QSPI Memory	SCK	P0.17
    QSPI Memory	CSN	P0.18
    QSPI Memory	IO0	P0.13
    QSPI Memory	IO1	P0.14
    QSPI Memory	IO2	P0.15
    QSPI Memory	IO3	P0.16
    LCD	Bit 1-2	P1.10 - P1.11
    LCD	Bit 3-8	P1.04 - P1.09
    LCD	RST	P0.25
    LCD	CS	P0.07
    LCD	RS	P0.06
    LCD	WR	P0.05
    LCD	RD	P0.04

4.2. MVP2

• Goals:

  • Integrate a Bluetooth Low Energy (BLE) game controller to enable game control through a micro:bit based gamepad.

  • This addition will enhance the gaming experience by allowing players to utilize the micro:bit as a game controller via wireless connectivity.

• Features:

  • BLE game controller;

• Required Hardware:

  • Nordic Semiconductor nRF5340 dev kit;

  • 3,5" ILI9486 display without touch feature;

  • micro:bit v2;

  • ELECFREAKS joystick v2;

• Pins mapping:

  • Nordic Semiconductor nRF5340 dev kit:

    Peripheral	Function	nRF5340 Pin
    Buttons	Button 1	P0.23
    Buttons	Button 2	P0.24
    Buttons	Button 3	P0.8
    Buttons	Button 4	P0.9
    LEDs	LED 1	P0.28
    LEDs	LED 2	P0.29
    LEDs	LED 3	P0.30
    LEDs	LED 4	P0.31
    SPI/SD card	SS	P1.12
    SPI/SD card	DI	P1.13
    SPI/SD card	DO	P1.14
    SPI/SD card	SCK	P1.15
    QSPI Memory	SCK	P0.17
    QSPI Memory	CSN	P0.18
    QSPI Memory	IO0	P0.13
    QSPI Memory	IO1	P0.14
    QSPI Memory	IO2	P0.15
    QSPI Memory	IO3	P0.16
    LCD	Bit 1-2	P1.10 - P1.11
    LCD	Bit 3-8	P1.04 - P1.09
    LCD	RST	P0.25
    LCD	CS	P0.07
    LCD	RS	P0.06
    LCD	WR	P0.05
    LCD	RD	P0.04

4.3. MVP3

• Goals:

  • Migrate from current display (connected via GPIO) to SPI one.

  • Support full screen.

• Features:

  • New display;

  • Full screen compatibility;

• Required Hardware:

  • Nordic Semiconductor nRF5340 dev kit;

  • 2.8" ILI9341 SPI display;

  • micro:bit v2;

  • ELECFREAKS joystick v2;

• Pins mapping:

  • Nordic Semiconductor nRF5340 dev kit:

    Peripheral	Function	nRF5340 Pin
    Buttons	Button 1	P0.23
    Buttons	Button 2	P0.24
    Buttons	Button 3	P0.8
    Buttons	Button 4	P0.9
    LEDs	LED 1	P0.28
    LEDs	LED 2	P0.29
    LEDs	LED 3	P0.30
    LEDs	LED 4	P0.31
    QSPI Memory	SCK	P0.17
    QSPI Memory	CSN	P0.18
    QSPI Memory	IO0	P0.13
    QSPI Memory	IO1	P0.14
    QSPI Memory	IO2	P0.15
    QSPI Memory	IO3	P0.16
    SPI/ILI9341	SCK	P1.15
    SPI/ILI9341	MOSI	P1.13
    SPI/ILI9341	MISO	P1.14
    SPI/ILI9341	CS	P1.12

4.4. MVP4

• Goals:

  • Return back to 4.3" FT810 SPI IPS display used in original nrf-doom project.

• Features:

  • Display supporting more than 30 FPS;

  • Full screen compatibility;

• Required Hardware:

  • Nordic Semiconductor nRF5340 dev kit;

  • 4.3" FT810 SPI IPS display;

  • micro:bit v2;

  • ELECFREAKS joystick v2;

• Pins mapping:

  • Nordic Semiconductor nRF5340 dev kit:

    Peripheral	Function	nRF5340 Pin
    Buttons	Button 1	P0.23
    Buttons	Button 2	P0.24
    Buttons	Button 3	P0.8
    Buttons	Button 4	P0.9
    LEDs	LED 1	P0.28
    LEDs	LED 2	P0.29
    LEDs	LED 3	P0.30
    LEDs	LED 4	P0.31
    QSPI Memory	SCK	P0.17
    QSPI Memory	CSN	P0.18
    QSPI Memory	IO0	P0.13
    QSPI Memory	IO1	P0.14
    QSPI Memory	IO2	P0.15
    QSPI Memory	IO3	P0.16
    SPI/FT810 Display	SCK	P0.06
    SPI/FT810 Display	MISO	P0.05
    SPI/FT810 Display	MOSI	P0.25
    SPI/FT810 Display	CS_N	P0.07
    SPI/FT810 Display	PD_N	P0.26

4.5. MVP5

• Goals:

  • Add option to connect BLE gamepad (Xbox wireless controller) and ideally BLE keyboard (built on RPi 400).

  • This step will enable full game control (all the available options).

• Features:

  • Using BLE gamepad.

  • Using BLE keyboard, which enables full-fledged game control per original manual (including cheats).

• Required Hardware:

  • Nordic Semiconductor nRF5340 dev kit;

  • 4.3" FT810 SPI IPS display;

  • Xbox controller;

  • Keyboard;

• Pins/buttons mapping:

  • Nordic Semiconductor nRF5340 dev kit:

    Peripheral	Function	nRF5340 Pin
    Buttons	Button 1	P0.23
    Buttons	Button 2	P0.24
    Buttons	Button 3	P0.8
    Buttons	Button 4	P0.9
    LEDs	LED 1	P0.28
    LEDs	LED 2	P0.29
    LEDs	LED 3	P0.30
    LEDs	LED 4	P0.31
    QSPI Memory	SCK	P0.17
    QSPI Memory	CSN	P0.18
    QSPI Memory	IO0	P0.13
    QSPI Memory	IO1	P0.14
    QSPI Memory	IO2	P0.15
    QSPI Memory	IO3	P0.16
    SPI/FT810 Display	SCK	P0.06
    SPI/FT810 Display	MISO	P0.05
    SPI/FT810 Display	MOSI	P0.25
    SPI/FT810 Display	CS_N	P0.07
    SPI/FT810 Display	PD_N	P0.26

  • Xbox controller:

    Xbox Button	Description
    Left Stick	Move forward/backward, look left/right;
    A Button	Cycle through available weapons;
    B Button	Fire current weapon / Select option in menu;
    X Button	Hold to run;
    Y Button	Open doors, activate switches;
    D-Pad Up	Move up in menu;
    D-Pad Down	Move down in menu;
    Left Trigger	Strafe left;
    Right Trigger	Strafe right;
    Back Button	Toggle automap view;
    Start Button	Show menu;

• Setup:

  • Xbox controller:

    1. Hold the pairing button on the front of the controller, until the light starts blinking quickly.

    2. Restart the board running the zephyrdoom project.

    3. Wait for 5-10 seconds.

    4. Hold the pairing button again, until the light stops blinking and stays on.

5. Release Notes

5.1. Fixed Bugs

• N/A

5.2. Known Bugs

• N/A

5.3. Implemented Improvements

5.3.1. MVP1

• N/A

5.3.2. MVP2

• FPS increase.

• Moved from proprietary radio com between gamepad and game to BLE com.

5.3.3. MVP3

• N/A

5.3.4. MVP4

• Moved to 4.3" FT810 SPI IPS display used in original nrf-doom project.

• More than 30 FPS.

5.3.5. MVP5

• N/A

5.4. Known Limitations

5.4.1. MVP1

• Low FPS (~8).

• Picture is rotated by 90°. Plus, we are not using full display area.

5.4.2. MVP2

• Low FPS (~14).

• Picture is rotated by 90°. Plus, we are not using full display area.

• BLE game controller requires manual setting of offsets (hard-coded) to eliminate drift. Calibration procedure could help to address this issue.

5.4.3. MVP3

• Low FPS (~5).

5.4.4. MVP4

• N/A

5.4.5. MVP5

• N/A