Get pIRCIS

App Store

The app is pIRCIS on the App Store, for iPhone and iPad, and it runs on a Mac with Apple silicon as an iPad app. The app's privacy policy and support page are on the website.

Board

You need:

• A 4.0" 320x480 ESP32 touch display. A Freenove FNK0114S, or any of the "cheap yellow display" boards of that size. Driven landscape at 480x320.
• A USB cable.
• Optionally a microSD card, for saving programs and run logs.

These boards ship with one of two display controllers. Mine is an ST7796, and everything here runs on it. There is an ili9488 build too. It compiles, but I have not run it, because I do not have a board with that controller. If you have one, I would like to know whether it works.

Flashing it

The easiest way is to build it yourself. On a Mac:

git clone https://github.com/jamesleaver/pIRCIS.git
cd pIRCIS
brew install platformio sdl2
pio run -e st7796 -t upload -t monitor

SDL2 is only for the emulator. Skip it if you just want to flash a board. On Linux, the same commands, with pip install platformio and apt install libsdl2-dev in place of the brew line.

On Windows, install Python (tick Add python.exe to PATH) and Git, then in PowerShell:

pip install platformio
git clone https://github.com/jamesleaver/pIRCIS.git
cd pIRCIS
pio run -e st7796 -t upload -t monitor

If you have already set up MSYS2 for the emulator (below), the same shell and the same pio flash the board too. Either way, if pio device list shows no port, Windows is missing the board's USB-serial driver -- CH340 or CP210x, depending on the board -- and Device Manager will show an unknown device until it is installed.

PlatformIO brings its own compiler and its own upload tool, so the build and flash commands are the same on all three systems.

If the screen stays dark or the colours look wrong, you have the other panel: use -e ili9488 instead. If upload cannot find the board, check pio device list. If the port is not there at all you are missing the USB-serial driver, not anything to do with PlatformIO. And if it sits on Connecting..... forever, hold the BOOT button, tap EN/RST, then let go of BOOT.

There are also prebuilt archives on Releases if you would rather not build. Grab the zip for your panel plus SHA256SUMS, check it, unzip it, and run ./flash.sh, or flash.bat on Windows. With no arguments either one lists the ports it can see. Flashing that way needs esptool, and on recent macOS you will need it in a virtual environment:

python3 -m venv ~/.venvs/esptool
source ~/.venvs/esptool/bin/activate
pip install esptool

On Windows, pip install esptool on its own is fine. The port is a COM number rather than a path, so it is flash.bat COM5 and Device Manager lists them under Ports.

Emulator

You don't need a board to try any of this. The emulator runs the real firmware in a window on your computer. Same interpreter, same screen, same programs. The mouse works as the touchscreen. The build asks your machine where SDL2 is rather than being told, so the last command is the same on all three systems; only the setup before it differs.

macOS

brew install platformio sdl2
git clone https://github.com/jamesleaver/pIRCIS.git
cd pIRCIS
pio run -e emulator -t exec

Linux

sudo apt install libsdl2-dev python3-pip git
pip install platformio
git clone https://github.com/jamesleaver/pIRCIS.git
cd pIRCIS
pio run -e emulator -t exec

Those are the Debian and Ubuntu package names; on other distributions install SDL2's development package and pip. If pip refuses to install system-wide, put PlatformIO in a virtual environment the way the Windows steps below do.

Windows

The emulator is built with MSYS2, which supplies the compiler and SDL2. Install it from PowerShell:

winget install --id MSYS2.MSYS2 -e

Then open MSYS2 MINGW64 from the Start menu -- that one, not "MSYS2 MSYS", which has the wrong compiler -- and run:

pacman -S --needed git mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2 mingw-w64-x86_64-pkg-config mingw-w64-x86_64-python
python -m venv ~/pio-venv
source ~/pio-venv/bin/activate 2>/dev/null || source ~/pio-venv/Scripts/activate
pip install platformio
git clone https://github.com/jamesleaver/pIRCIS.git
cd pIRCIS
pio run -e emulator -t exec

MSYS2's Python will not install packages system-wide, which is what the virtual environment is for; run the source line again in each new shell before pio, or put it in ~/.bashrc. The first build downloads the toolchain and takes a few minutes; after that it is seconds. If the build cannot find SDL2, point SDL2_DIR at the folder holding include and lib -- /mingw64 for an MSYS2 install.

Driving it from the keyboard

Set SYS > KEYBOARD to REAL and the on-screen keyboards go away, because you have a real one. The shortcut list comes up when you switch it over, and F1 brings it back.

On RUN the arrows scroll the view. If SYS > GRID TAP is set to inspect cells or to move the start point, they move between cells instead and Space does whatever that setting says. Inside the inspector the arrows move the cell, and e, r, s and c press its buttons: edit the character, revert it, set the start point, close. The character keyboard has no space key; DEL then OK writes a space.

In the editor the letters go into the program, so the commands above do not apply there. Ctrl or Cmd with S, Z, Y, N and G save, undo, redo, rename and switch the grid view. Ctrl or Cmd with Shift and ? brings up the shortcut list, ? being the symbol on the editor's help button.

The window itself answers to Alt-R and Alt-L to rotate and Alt-1 to Alt-6 to scale. Those need Alt so that r, l and the digits stay ordinary characters in a program.

There is a version with no window at all, for running a program and looking at what it did:

cd host && make
./sk_emu --grid myprogram.txt --stats
./sk_emu --visits