PX-42F App Manual

1. What an app is

An app is a program for the PX-42F itself, written in C. It's a single .bin file on the calculator's drive, in /BIN/GAMES or /BIN/APPS, and it starts from Settings → Games & Apps. While it runs it has the whole calculator: the screen, the keyboard, the speaker, the clock, the files on the drive, the USB serial port, the infrared LED and the battery.

An app talks to the calculator only through one table of functions, px. Its definition is px42f/px_app.h, the contract between the firmware and every app. This manual explains each function in it. The rest of the template project is the build setup, a runtime, and a simulator that runs your app on your computer.

2. Quick start

What you need

• The ARM toolchain. Use the one the Raspberry Pi Pico extension for VS Code installs: ~/.pico-sdk/toolchain/15_2_Rel1. Another location works with make PICO_TOOLCHAIN=/path/to/toolchain.
• For the simulator: make, python3 and a C compiler for your computer (cc). On a Mac, they come with the Xcode Command Line Tools.
• Optional: VS Code with the C/C++ extension. Everything also works with make in a terminal.

Make a new app

1. Copy the PX-42F-App-Template folder and give the copy your app's name, for example PX-42F-Tetris. Open it in VS Code.
2. In the Makefile, set two things:
   • NAME: the file name, which is also the name in the menu. Use up to 28 letters, digits, _ or -.
   • KIND: GAMES or APPS, the folder it goes in.
3. Write your app in src/app.c. You can add more .c and .h files in src/; they're all built.
4. Build it: ⇧⌘B in VS Code, or make. The result is build/NAME.bin.
5. Try it on your computer: the Simulate task, or make sim. Screenshots are saved in build/sim-out.
6. Put it on the calculator:
   1. On the calculator, open Settings → USB Drive → Connect to Computer.
   2. Run the Install on the PX-42F task, or make install. It copies the file to BIN/GAMES or BIN/APPS on the drive named PX-42F.
   3. Eject the drive on the computer, then press EXIT on the calculator.
7. Start it: Settings → Games & Apps → Games (or Apps), choose it, and press ENTER.

The project

3. Your first app

Every app includes px.h and defines app_main(). The firmware calls it with the table px already set. This app shows a greeting and waits until you leave:

#include "px.h"

int app_main(void) {
    px->clear();                                        /* a white screen */
    px->text(4, 4, "Hello, PX-42F!", PX_FONT_LARGE, 0); /* black text at (4, 4) */
    px->show();                                         /* send it to the panel */

    while (px->key(-1) != PX_KEY_QUIT)                  /* wait, asleep, for ON */
        ;
    return PX_EXIT_MENU;                                /* back to the menu */
}

Three things to notice:

• Drawing happens in memory. Nothing reaches the panel until px->show().
• px->key(-1) waits for the next key, asleep. It returns PX_KEY_QUIT when you press ON, and the app must then return.
• The return value says where to go. PX_EXIT_MENU goes back to the list; PX_EXIT_OFF turns the calculator off.

4. How an app runs

Starting

When you choose an app, the calculator:

1. Reads the whole .bin and checks its header and checksum. A file that fails gets a message (section 19) and nothing else happens.
2. Saves the calculator's memory (the Plus42 stack, registers and programs) to the drive.
3. Copies the app into RAM at 0x20060000, sets its variables to zero, and calls app_main() on processor core 1.

When the app returns, the calculator takes its memory back and goes to the menu, or turns off.

Rules every app follows

If an app crashes

The calculator's memory was saved to the drive before the app started, so nothing is lost. A crash or a hang restarts the calculator. The start screen then shows where it stopped: see Debugging.

Speed and battery

The processor runs at 150 MHz while the app works and at 48 MHz while it waits in px->key() or px->sleep(), asleep between keys and timeouts. A game that waits there for each frame uses little more than the calculator idling. A loop that never waits uses about six times as much, and trips the watchdog anyway.

5. The screen

The screen is 250 × 122 pixels, black and white. (0, 0) is the top-left corner, x goes right and y goes down. Everything you draw goes into a picture in memory; px->show() sends it to the panel. Draw a whole frame, then show it once.

Every drawing function leaves out whatever falls off the screen, so you can draw at any coordinates.

void show(void);

void clear(void);

void pixel(int x, int y, int black);

int get_pixel(int x, int y);

void fill(int x, int y, int w, int h, int black);

px->fill(0, 0, PX_SCREEN_W, 12, 1);   /* a black title bar */
px->fill(40, 30, 50, 20, 1);          /* a box with a 2-pixel border */
px->fill(42, 32, 46, 16, 0);

void line(int x0, int y0, int x1, int y1, int black);

void bitmap(int x, int y, int w, int h, const uint8_t *bits, int stride);

/* An apple, 5 x 5: one byte a row, the pixels in the top 5 bits. */
static const uint8_t apple[5] = {0x20, 0x70, 0xF8, 0xF8, 0x70};
px->bitmap(100, 50, 5, 5, apple, 1);

int text(int x, int y, const char *s, int font, int inverse);

int x = px->text(2, 20, "Score: ", PX_FONT_SMALL, 0);
px->text(x, 20, "42", PX_FONT_SMALL, 1);           /* the number inverted */

int text_width(const char *s, int font);
int font_height(int font);

const char *t = "GAME OVER";
px->text((PX_SCREEN_W - px->text_width(t, PX_FONT_LARGE)) / 2, 50, t, PX_FONT_LARGE, 0);

uint8_t *screen;

/* Invert the whole screen. */
for (int i = 0; i < PX_SCREEN_H * PX_SCREEN_STRIDE; i++)
    px->screen[i] ^= 0xFF;
px->show();

6. Fonts and characters

The built-in fonts are always the same, so a layout drawn with them looks as you designed it on every calculator.

Character codes

Codes 32–126 are ASCII, except 94, which is ↑ (the HP-42S has no ^ there; ^ is code 30). Codes 0–31 and 127 are the HP-42S's symbols. Write them in C strings as \x escapes:

px->text(2, 2, "\x05+ turns left", PX_FONT_SMALL, 0);   /* Σ+ turns left  ("+" isn't a hex digit) */
px->text(2, 16, "20\x13" "C", PX_FONT_SMALL, 0);        /* 20°C */
px->text(2, 30, "\x07r\x1e" "2", PX_FONT_SMALL, 0);     /* πr^2 */

The font maps

Every character of the built-in fonts. A character's code is its row (00 to 70, in hexadecimal) plus its column (0 to F).

7. The keyboard

Keys are named by where they sit: PX_KEY(row, col), row 0–6 from the top and column 0–5 from the left. The top two rows have 6 keys and the others 5. ENTER is PX_KEY(2, 0). The same places name keys in the IR Remote's files (R0C5 is XEQ).

Orange: the name after PX_KEY_ in px_app.h, for example PX_KEY_ENTER.

int key(int wait_ms);

void on_key(int on_is_key);    /* API version 3 */

Waiting for a key

/* The next key pressed (releases skipped), or PX_KEY_QUIT. */
static int wait_key(void) {
    while (1) {
        int k = px->key(-1);
        if (k == PX_KEY_QUIT || !(k & PX_KEY_RELEASED))
            return k;
    }
}

Keys that are held down

Track down and up events to know what's held, for example to move while a key is held:

static bool held[64];                  /* by PX_KEY(row, col) */

int k = px->key(0);
if (k >= 0)
    held[k & 63] = !(k & PX_KEY_RELEASED);
if (held[PX_KEY(4, 1)]) x--;           /* 4 held: left */
if (held[PX_KEY(4, 3)]) x++;           /* 6 held: right */

8. Time and random numbers

uint32_t millis(void);

void sleep(int ms);

void datetime(px_datetime_t *now);

typedef struct {
    int32_t year;    /* 2026 */
    int32_t month;   /* 1-12 */
    int32_t day;     /* 1-31 */
    int32_t hour;    /* 0-23 */
    int32_t min;     /* 0-59 */
    int32_t sec;     /* 0-59 */
    int32_t ms;      /* 0-999 */
    int32_t weekday; /* 0 = Sunday ... 6 = Saturday */
} px_datetime_t;

px_datetime_t now;
px->datetime(&now);
char line[24];
snprintf(line, sizeof(line), "%02ld:%02ld:%02ld", (long) now.hour, (long) now.min, (long) now.sec);

uint32_t random(void);

9. Sound

The PX-42F has a small speaker, and plays one sound at a time: starting a sound stops the one playing. The calculator's second processor plays it, so a sound can play while the app carries on:

• tone() and play() wait until the sound has played. Use them where the next thing should come after it.
• tone_async() and play_async() start the sound and return at once. Use them in a game: the frames keep coming while it plays.

A sound still playing when the app ends is stopped. While a sound plays, the processor stays at full speed (the speaker's timing comes from its clock), so waiting in key() then saves less battery.

void tone(int tone);

int play(const char *path);

px->play("/SOUNDS/ON.wav");     /* the calculator's turn-on sound */
px->play("COIN.wav");           /* /BIN/GAMES/MYGAME/COIN.wav */

void tone_async(int tone);
int play_async(const char *path);

if (ate_apple)
    px->tone_async(9);         /* a short high tone; the next frame doesn't wait */

int sound_playing(void);
void sound_stop(void);

px->play_async("MUSIC.wav");
while (px->sound_playing() && px->key(100) != PX_KEY_QUIT)
    ;                          /* music until it ends or ON */
px->sound_stop();

int midi_play(const char *path);    /* API version 4 */
void midi_status(px_midi_status_t *status);

if (px->midi_play("/MIDI/Canon.mid") == 0) {
    px_midi_status_t st;
    while (px->sound_playing() && px->key(100) != PX_KEY_QUIT) {
        px->midi_status(&st);
        /* draw st.elapsed_ms / st.length_ms */
    }
    px->sound_stop();
}

10. Files on the drive

The calculator's drive is a FAT disk in its flash memory, 12 MB. A computer sees the same files in USB Drive mode, so an app can read files you copy there (levels, pictures, sounds, data) and write files you can copy off.

Paths

• From the top of the drive: a path starting with /, such as "/SOUNDS/ON.wav" or "/STATE".
• In the app's own folder: any other path, such as "BEST" or "levels/1.txt". The folder is next to the app and named after it: /BIN/GAMES/SNAKE/ for /BIN/GAMES/SNAKE.bin. It's made the first time the app writes a file in it.
• "" is the app's folder itself, for list().
• A path has at most PX_PATH_MAX (96) characters. Names aren't case-sensitive, as on any FAT drive.

Whole files

int load(const char *path, void *data, int size);

int save(const char *path, const void *data, int size);

/* A best score, kept as text so it can be read on a computer. */
static int load_best(void) {
    char text[12] = "";
    return px->load("BEST", text, sizeof(text) - 1) > 0 ? atoi(text) : 0;
}

static void save_best(int best) {
    char text[12];
    int n = snprintf(text, sizeof(text), "%d\n", best);
    px->save("BEST", text, n);
}

Reading and writing in pieces

int open(const char *path, const char *mode);
int read(int file, void *data, int size);
int write(int file, const void *data, int size);
int close(int file);

/* Copy a log line by line to the console. */
int f = px->open("/LOG.TXT", "r");
char buf[256];
int n;
while (f >= 0 && (n = px->read(f, buf, sizeof(buf))) > 0)
    px->serial_write(buf, n);
if (f >= 0)
    px->close(f);

Folders

int list(const char *dir, const char *ext, char (*names)[PX_FILE_NAME_MAX + 1], int max);

static char levels[20][PX_FILE_NAME_MAX + 1];
int count = px->list("", ".lvl", levels, 20);    /* "1", "2", ... for 1.lvl, 2.lvl */

int mkdir(const char *path);
int remove(const char *path);

11. The USB serial console

Connected to a computer by USB, the calculator shows up as two serial ports. The first, "PX-42F Console", belongs to the app while it runs.

int serial_write(const void *data, int size);
int serial_read(void *data, int size);

printf() works too. The runtime sends stdout to the console a line at a time, so end lines with \n. The C library is newlib-nano: %f isn't supported by default. Print a float as two integers, or link with -u _printf_float (about 10 KB more).

printf("level %d, score %d\n", level, score);

To watch it on a Mac, open the first of its two ports in a terminal (ls /dev/cu.usbmodem* lists them): screen /dev/cu.usbmodem2101 115200, with your port's name. Leave with Ctrl-A then K. On Windows, use PuTTY or the Arduino IDE's serial monitor on the console's COM port.

12. Infrared

The PX-42F has an infrared LED on its top edge, the kind TV remotes use. It's driven by hardware, so an app can send any remote-control code with exact timing.

void ir_send(const px_ir_burst_t *burst);

typedef struct {
    uint32_t carrier_hz;              /* the blinking while "on": 10000-100000, usually 38000 */
    int32_t count;                    /* how many times in us[]: 2-112 */
    uint32_t us[PX_IR_MAX_TIMINGS];   /* microseconds, alternately off and on */
} px_ir_burst_t;

/* NEC: address 0x04, command 0x08 (a TV's power, for example). */
static void nec_send(uint8_t address, uint8_t command) {
    static px_ir_burst_t b;
    uint8_t bytes[4] = {address, (uint8_t) ~address, command, (uint8_t) ~command};
    b.carrier_hz = 38000;
    b.count = 0;
    b.us[b.count++] = 110000;                  /* gap since the last one */
    b.us[b.count++] = 9000;                    /* leader: on 9 ms */
    b.us[b.count++] = 4500;                    /*         off 4.5 ms */
    for (int i = 0; i < 32; i++) {
        b.us[b.count++] = 560;                 /* each bit: on 560 us */
        b.us[b.count++] = (bytes[i / 8] >> (i % 8)) & 1 ? 1690 : 560;   /* off: 1 long, 0 short */
    }
    b.us[b.count++] = 560;                     /* the final pulse */
    px->ir_send(&b);
}

The PX-42F has no infrared receiver, so it can send codes but not learn them.

13. Power

int battery_mv(void);

int usb_connected(void);

Turning off. Return PX_EXIT_OFF from app_main() to turn the calculator off when the app ends. The calculator also turns off after ON is held for 2 seconds, when the Sleep Timer runs out, or when the battery is empty: key() returns PX_KEY_QUIT for each, then the app returns.

14. Decimal numbers

The calculator computes with IEEE 754 decimal128 numbers, from Intel's decimal library, as Plus42 does: 34 significant digits, exponents up to ±6144, and decimal, so 0.1 + 0.2 is exactly 0.3. An app can use the same numbers and functions through the table, with no library of its own. They need firmware with API version 2.

typedef struct { uint32_t w[4]; } px_dec_t;   /* 16 bytes, aligned to 16 */

int dec(int op, px_dec_t *r, const px_dec_t *a, const px_dec_t *b);

void dec_from_int(px_dec_t *r, int32_t v);
int dec_to_int(int32_t *r, const px_dec_t *a);
int dec_from_string(px_dec_t *r, const char *s);
void dec_to_string(char buf[PX_DEC_STRING_MAX], const px_dec_t *a);

int dec_cmp(const px_dec_t *a, const px_dec_t *b);
int dec_class(const px_dec_t *a);

/* The square root of 2, to 34 digits, on the console. */
px_dec_t two, root;
char s[PX_DEC_STRING_MAX];
px->dec_from_int(&two, 2);
px->dec(PX_DEC_SQRT, &root, &two, NULL);
px->dec_to_string(s, &root);
printf("%s\n", s);      /* +1414213562373095048801688724209698E-33 */

15. Recipes

A game loop

Draw a frame, then wait for the next one in key(), handling the keys that come meanwhile. The calculator sleeps between frames, and the frames keep time even when keys are pressed.

#define FRAME_MS 50   /* 20 frames a second */

/* The next key before time t, or PX_KEY_NONE at t. A frame that's late
 * doesn't wait at all: a negative wait would mean "forever". */
static int key_before(uint32_t t) {
    int32_t left = (int32_t) (t - px->millis());
    return px->key(left > 0 ? (int) left : 0);
}

int app_main(void) {
    uint32_t next = px->millis();
    while (1) {
        update();             /* move things */
        draw();               /* draw the frame, then px->show() */
        next += FRAME_MS;
        int k;
        while ((k = key_before(next)) != PX_KEY_NONE) {
            if (k == PX_KEY_QUIT)
                return PX_EXIT_MENU;
            if (!(k & PX_KEY_RELEASED))
                handle_key(k);
        }
    }
}

A menu

/* Up and down move, ENTER chooses. Returns the item, or -1 to quit. */
static int menu(const char *title, const char *const *items, int count) {
    int sel = 0;
    while (1) {
        px->clear();
        px->fill(0, 0, PX_SCREEN_W, 12, 1);
        px->text(2, 0, title, PX_FONT_SMALL, 1);
        for (int i = 0; i < count; i++) {
            if (i == sel)
                px->fill(0, 14 + i * 13, PX_SCREEN_W, 13, 1);
            px->text(4, 15 + i * 13, items[i], PX_FONT_SMALL, i == sel);
        }
        px->show();
        int k = px->key(-1);
        if (k == PX_KEY_QUIT)
            return -1;
        if (k == PX_KEY_ENTER)
            return sel;
        if (k == PX_KEY_ARROW_UP)
            sel = (sel + count - 1) % count;
        if (k == PX_KEY_ARROW_DN)
            sel = (sel + 1) % count;
    }
}

Reading a text file line by line

static char text[16 * 1024];             /* static: too big for the stack */

int n = px->load("words.txt", text, sizeof(text) - 1);
if (n >= 0) {
    text[n] = 0;
    for (char *line = strtok(text, "\r\n"); line; line = strtok(NULL, "\r\n"))
        add_word(line);
}

Typing a number

The digit keys' places: 0 is PX_KEY(6, 1); 1, 2, 3 are row 5; 4, 5, 6 row 4; 7, 8, 9 row 3, columns 1 to 3.

/* The digit on a key, or -1. */
static int digit_of(int k) {
    int r = PX_KEY_ROW(k), c = PX_KEY_COL(k);
    if (k == PX_KEY(6, 1))
        return 0;
    if (r >= 3 && r <= 5 && c >= 1 && c <= 3)
        return (5 - r) * 3 + c;
    return -1;
}

16. The simulator

make sim (the Simulate task) builds your app for your computer, with a stand-in for the calculator, and runs it through a script of keys and pauses. It saves screenshots as PNG files: the quickest way to see a change, and to check that a game behaves, without copying anything to the calculator.

The script is SIM_SCRIPT in the Makefile. It's a list of words, run in order:

SIM_SCRIPT := shot:title ENTER 1500 shot:playing XEQ 900 SIGMA 2000 shot:later ON

• Time is virtual. It moves on through pauses and the app's waits, and by 1 ms each time the app reads it, so a loop that never waits still sees time pass. A 10-second script runs in a moment, and the same script gives the same result every time. The random numbers are the same on each run too.
• The drive is a folder. sim/drive holds what the calculator's drive would: put files the app reads there, at the same paths. Each make sim works on a fresh copy, build/sim-drive, so what the app writes doesn't pile up in your project.
• What's printed. Sounds, IR transmissions and serial output are printed, with the virtual time.
• Memory checks. The simulator is built with AddressSanitizer: writing past an array stops it and says where.

Run the simulator yourself to try other scripts: build/sim OUT_DIR DRIVE_DIR WORD....

The live simulator

make live (the Simulate live task) runs the same simulator in your browser, at http://127.0.0.1:8042. Only your computer can reach that address. It uses the computer's clock, not a script: the page shows the screen as the app draws it, and you press the keys yourself, by clicking the keypad or typing (digits and . + - * /, Enter, Backspace, the arrow keys, Space for R/S, f for SHIFT, s for Σ+, x for XEQ and Esc for ON).

• Restart rebuilds the app and starts it again with a fresh copy of the drive: edit src/app.c, press Restart, look. A build that fails shows its errors in the console.
• Record writes down the keys you press, and the pauses between them, as a SIM_SCRIPT line to paste into the Makefile: play the app by hand once, then run it as a test with make sim.
• The console shows what the simulator prints, and the sanitizers' report if the app crashes. The box under it sends text to the app's USB serial port, then Enter.
• Sounds play in the page. play() and tone() use the WAV files in the simulated drive's SOUNDS folder (sim/drive/SOUNDS/ON.wav, TONES/TONE0.wav …), as on the calculator, and the app waits as long as the sound lasts. The browser keeps sound off until you click or press a key on the page once. make sim still only prints them.

It needs python3, which the simulator needs already. Stop it with Ctrl-C in the terminal.

17. Debugging

Print

printf() to the USB console (section 11) is the simplest tool: print what the app does, and watch it in a terminal.

A crash

When an app crashes, the calculator restarts. Its start screen shows a report until a key is pressed:

Last reset:
FAULT core1 PC=20060C41 LR=200608B5 ...

Addresses from 20060000 up are in your app. The app is linked at the address it runs at, so the toolchain can name the line:

~/.pico-sdk/toolchain/15_2_Rel1/bin/arm-none-eabi-addr2line -f -e build/NAME.elf 0x20060C41 0x200608B5

PC is where it stopped; LR is usually the function that called it. Build with -g (add it to CFLAGS) for exact lines. build/NAME.map lists where every function and variable is.

A hang

An app that runs 100 ms without calling into px is restarted by the watchdog. The start screen then says WATCHDOG RESET APP: the app was in its own code, in a loop that doesn't wait.

18. The .bin file and the build

A .bin is the app's memory image as it will be in RAM, from 0x20060000. It starts with a 24-byte header:

All fields are 32-bit little-endian (px_app_header_t in px_app.h).

The build. make does this:

1. arm-none-eabi-gcc compiles and links src/*.c with px42f/runtime.c for the RP2350's Cortex-M33: Thumb code, -mfloat-abi=softfp as the firmware uses, -Os, and the newlib-nano C library without its start-up code.
2. px42f/app.ld puts the header first, then code, constants and data, all at 0x20060000. The zeroed variables come after, then the heap. A section the script doesn't place stops the link (--orphan-handling=error), so nothing ends up outside the image.
3. objcopy takes the image out of the .elf, and px42f/pxbin.py fills in the sizes and the CRC.

The C library is there: string.h, stdlib.h (with malloc), stdio.h's snprintf and printf, ctype.h. float runs on the processor's FPU; double works too, more slowly, in software. math.h needs -lm added to LDFLAGS.

19. Messages when an app won't start

20. Versions

px_app.h has PX_APP_API_VERSION, now 4. Version 2 added the decimal numbers, version 3 on_key(), version 4 MIDI. New firmware only adds functions at the end of the table and raises the number, so:

• An app keeps working on every later firmware.
• A calculator with older firmware than the app was built for refuses it ("Needs a newer firmware"), rather than calling a function it doesn't have.
• To use functions a newer firmware adds, copy its px_app.h (from the PX-42F-Plus firmware project) into your app's px42f/ folder and rebuild. Your app then needs that firmware too.

px->version is the firmware's own version number, for an app that wants to use a newer function only where it exists.

21. All functions at a glance