pupdate

A free utility for updating openFPGA cores, firmware, and related assets on your Analogue Pocket. It can run as an interactive console menu or from the command line.

A browsable list of available cores is here: openFPGA cores inventory.

Please use the latest release before reporting issues; older builds are not supported.

---

Easy mode

Do not clone the repo if you only want to run the tool. Download the latest release, unzip it, place the executable for your OS on the root of your SD card (or another folder you use as the install path), and run it.

Use Settings from the main menu to walk through toggles, or edit pupdate_settings.json for advanced options. In the full-screen UI (--tui) the same options live on the Settings tab, grouped — see Settings.

macOS specific

In most macOS default installation setups, you will likely encounter issues running the script the "easy way". The following command will remove the quarantine from the pupdate script only. ⚠️ Use sparingly ⚠️

xattr -d com.apple.quarantine /path/to/pupdate

---

Interactive menu

The full menu tree is documented in MENU.md.

---

What Pupdate does (overview)

Area What it covers Cores Downloads and updates openFPGA cores from the library inventory; optional local inventory files; per-core skip, assets, rename, display modes, extras, and version pinning Firmware Checks for and installs Analogue Pocket firmware Assets ROMs, BIOS, and other files from configured archives (archive.org, custom, core-specific) Pocket setup Display modes, image packs, library images, Game Boy palettes, instance JSON (e.g. PC Engine CD), Game & Watch ROM build flow, Super GameBoy aspect ratio, Analogizer config, Patreon Config (email, Patreon session cookie for JT beta auto-fetch, cookie test), Directory Locations (backup saves path, archive cache, temp directory), GitHub token (API rate limits), debug helpers Maintenance Update/install/reinstall/uninstall cores, ROM set archives, prune save states, clear archive cache, pin/unpin core versions, validate/repair core JSON Extras Pocket Extras (additional assets, combination platforms, variant cores) from pocket_extras.json Plugins Plugins for custom functionality

---

RTFM (quick links)

Update All · Update Firmware · Select Cores · Download Assets · Backup Saves & Memories · Pocket Setup · Pocket Maintenance · Pocket Extras · Plugins · Pin / unpin core version · Settings · Additional settings · Asset archives · CLI · Jotego beta · Analogizer · Troubleshooting · Developers

Update All

The “do everything” option. Steps marked with * follow your Settings toggles.

1. Check for firmware updates *
2. Compress and backup Saves and Memories *
3. Install/update every selected core
4. Download missing required assets for selected cores *
5. Remove cores you have not selected (when that option is enabled) *
6. Run the instance JSON builder for supported cores (e.g. PC Engine CD) when enabled *
7. Rename Jotego cores to friendly titles when enabled *

Pinned versions: If a core has pinned_version set in settings, the updater resolves that version from the inventory release list only. If the pin does not match any listed release, that core is skipped with a message and the run continues.

Update Selected

(Pocket Maintenance) — Pick installed cores to update.

Install Selected

(Pocket Maintenance) — Pick cores you do not have installed yet; installs them without running a full Update All.

Update Firmware

Checks for Pocket firmware updates only, then exits.

Select Cores

Asks how new cores should be handled:

• Yes — All current cores selected; new cores auto-install as they appear.
• No — New cores are not installed automatically; you are not prompted. You then choose from the full list which cores to manage.
• Ask — Each run can prompt for new cores; you still choose from the full list for your baseline.

Download Assets

Fetches missing assets (ROMs, BIOS, etc.) for selected cores from your configured archives.

You supply your own ROMs for non-arcade cores where the archive does not provide them.

Backup Saves & Memories

Zips the Pocket Saves and Memories folders to the path in settings (default: Backups next to the executable unless overridden).

---

Pocket Setup

Display modes

• Enable Recommended Display Modes — Applies the curated list from display_modes.json to the cores that reference those modes.
• Enable Selected Display Modes — You pick modes from the full list; they are applied to all installed cores that support them.
• Enable Selected Display Modes for Selected Cores — Same picker, then you choose which installed cores receive them.
• Reset All / Selected Customized Display Modes — Restore core defaults.
• Change Display Modes Option Setting — Merge (combine with core defaults), Overwrite (replace), or Ask each time.

To override the hosted display_modes.json, place a copy next to the executable and set use_local_display_modes to true.

Download Platform Image Packs

Lists image packs (from image_packs.json), downloads and extracts to Platforms/_images.

Download Pocket Library Images

• Spiritualized1997 (GB, GBC, GBA, GG) — hardcoded in the app: Library_Image_Set_v1.0.zip from your configured archive.
• All other submenu titles and items come from pocket_library_images.json (bundled next to the executable), same idea as Pocket Extras. Each group has a menu_title (submenu label) and entries with menu_label, id, github_user, github_repository, and sources: an array of release_asset (zip on the release), path_under_extract (folder path inside that zip to .bin files, /-separated), and dest_images_subfolder (under System/Library/Images/ on the device). Optional post_install_note is printed after a successful install (when any files were copied). Enable Use a local pocket_library_images.json file in Settings to read only the local copy instead of fetching the catalog from GitHub (see use_local_pocket_library_images in pupdate_settings.json).

CLI (like pocket-extras): pocket-library-images alone installs Spiritualized. pocket-library-images -l lists catalog entry id values; -n <id> installs that entry; -n <id> -i prints details. Example: pocket-library-images -n codewario_boxarts.

Download GameBoy Palettes

Downloads palette packs maintained by davewongillies and others (see original palette credits in prior releases); large collection of official and community palettes.

Generating instance JSON files (PC Engine CD)

• Supported workflow is centered on PC Engine CD; put games under /Assets/{platform}/common, one game per folder (full game title as folder name).
• Games should be cue/bin. The generated JSON uses the cue file name as the base name—name the cue with the full title too.
• Update All or Generate Instance JSON Files walks common and builds launch JSONs.
• Disable in Update All with build_instance_jsons: false in settings.
• Optional: local ignore_instance.json with use_local_ignore_instance_json if you maintain exclusions.

Generate Game & Watch ROMs

Create:

• /Assets/gameandwatch/agg23.GameAndWatch/artwork
• /Assets/gameandwatch/agg23.GameAndWatch/roms

Put [game].zip in each; run the menu item to build. Game & Watch asset downloads are configured under archives (core-specific archive for agg23.GameAndWatch)—enable/configure there rather than a separate global toggle.

Super GameBoy aspect ratio

Apply 8:7 to chosen Spiritualized.SuperGB* cores, or restore 4:3.

Analogizer Config

Jotego vs Standard wizards for Analogizer JSON. See Analogizer setup.

Patreon Config

Submenu under Pocket Setup.

• Set Patreon Session Cookie (for JT Beta auto-fetch) — Stores your browser session_id cookie for experimental Patreon-based jtbeta.zip auto-fetch. See Jotego beta for full steps and caveats.
• Test Patreon Session Cookie — Verifies the cookie and whether the account is a Jotego patron (diagnostic only).

Directory Locations

Submenu under Pocket Setup.

• Set Backup Saves Location — Folder where Backup Saves & Memories writes zip files. Default Backups is a relative path (resolved from the process current directory when the tool runs; use an absolute path if you need a fixed location). Clearing the value when prompted resets to Backups. Same as config.backup_saves_location in JSON.
• Set Archive Cache Location — When Cache downloaded archive files locally is enabled, this overrides the default cache folder under your user LocalApplicationData pupdate\cache (Windows) / equivalent. Leave empty (or save an empty line) to use that default. Same as config.archive_cache_location.
• Set Temp Directory — Where pupdate extracts downloads and temporary files. Empty means the OS temp folder (Path.GetTempPath()). Same as config.temp_directory.

Set GitHub Token

Stores a personal access token for GitHub API calls (higher rate limits than anonymous requests). The current value is shown when you open this item. You can also set config.github_token in pupdate_settings.json.

Print openFPGA Category Structure

Prints a summary of platform categories and cores (debug / reference).

---

Pocket Maintenance

• Update Selected / Install Selected — See above.
• Reinstall All / Select Cores — Clean reinstall of core files (ROMs and saves are not removed).
• Uninstall Select Cores — Optional removal of core-specific Assets; ROMs/saves untouched.
• Manage ROM Set Archives — Sync and manage ROM set definitions (romsets.json).
• Prune Save States — Trims old save states under Memories.
• Clear Archive Cache — Deletes cached archive downloads when cache archive files is enabled.
• Pin/Unpin Core Version — See next section.

---

Pin / unpin core version

For installed cores with a GitHub-backed inventory entry:

1. Choose Unpin, Select from releases list, Enter version manually, or Go Back.
2. Select from releases list opens a paginated list of versions from the inventory (newest-first by release date). Pick one to pin.
3. Enter version manually stores any string; it must match a metadata.version value in the inventory’s releases array for updates to succeed.

Update behavior: The pinned ZIP URL is taken only from the inventory release that matches the pin (with simple v prefix normalization). There is no GitHub API fallback for pins. If the pin is missing from releases, the core is skipped for that run with a clear message.

---

Pock