Current Release Downloads Donate

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.

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 email, debug helpers
Maintenance Update/install/reinstall/uninstall cores, ROM set archives, prune save states, clear archive cache, pin/unpin core versions
Extras Pocket Extras (additional assets, combination platforms, variant cores) from pocket_extras.json

Update All · Update Firmware · Select Cores · Download Assets · Backup Saves & Memories · Pocket Setup · Pocket Maintenance · Pocket Extras · Pin / unpin core version · Settings · Additional settings · Asset archives · CLI · Jotego beta · Analogizer · Coin-Op beta · 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:

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

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

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)

Generate Game & Watch ROMs

Create:

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.

Set Patreon Email Address

Used with Coin-Op Collection beta license fetch; also editable here if you change Patreon email.

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

Pocket Maintenance

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.

Pocket Extras

Third-party bundles defined in pocket_extras.json. Each entry can show a description and links before install (show_menu_descriptions in settings).

Exact menu labels are built at runtime; see MENU.md for a current snapshot.

Settings

Toggles exposed in the Settings menu (stored in pupdate_settings.json):

Name Description
Download Firmware Updates Firmware check during Update All
Download Missing Assets Asset check during Update All
Build game JSON Files Instance JSON builder during Update All
Delete cores, not managed by pupdate Remove unmanaged cores from SD when enabled
Automatically rename Jotego cores Friendly platform names after install
Use CRC check Verify assets by CRC; re-download if mismatch
Preserve Platforms folder Avoid overwriting Platforms on Update All
Skip alternative ROMs Ignore _alternatives folders when fetching assets (default on)
Compress and backup Saves and Memories Backup during Update All
Show Menu Descriptions Prompts/descriptions for Pocket Extras and similar
Use custom archive Use the preconfigured “custom” archive entry instead of default archive.org
Automatically install updates to Pupdate Self-update without prompt on startup
Use Local Pocket Extras Use local pocket_extras.json
Use Local Display Modes Use local display_modes.json
Cache downloaded archive files locally Keep a reusable cache; optional cache path in JSON
Coin-Op Collection Beta Access Enables beta license flow (see Coin-Op)
Adds a description element to the video.json display modes Non-breaking extra field in generated video JSON
Hide and uninstall Analogizer core variants Hides Analogizer-specific core variants

Game & Watch (and other core-specific archives) are enabled in the archives array in JSON, not via a separate Settings row.

Additional settings

Edit pupdate_settings.json for keys that are not bool menu toggles:

Name Description
config.github_token Used for GitHub API calls (rate limits)
config.download_new_cores yes / no / ask — set by Select Cores
config.display_modes_option merge / overwrite / ask
config.patreon_email_address Patreon email for Coin-Op beta license
config.backup_saves_location Backup output directory
config.temp_directory Override temp extract path (default: under install path)
config.archive_cache_location Override archive cache directory when caching is on
config.suppress_already_installed Reduce “already installed” console noise
config.use_local_cores_inventory Use local cores.json and platforms.json (openFPGA Library v3 format) next to the executable
config.use_local_blacklist Use local blacklist.json instead of downloading
config.use_local_image_packs Use local image_packs.json
config.use_local_ignore_instance_json Use local ignore_instance.json
archives Archive definitions: internet_archive, custom_archive, core_specific_archive, core_specific_custom_archive (see below)
credentials.internet_archive Optional archive.org username/password
core_settings.<core_id>.* Per core: skip, download_assets, platform_rename, pocket_extras, pocket_extras_version, display_modes, original_display_modes, selected_display_modes, requires_license, pinned_version

Asset blacklist

blacklist.json lists filenames not downloaded as assets. Entries support * and ? wildcards; matching applies to the full slot path and to the file name alone (useful for paths like subfolder/game.bin).

Asset source archives

The archives array in pupdate_settings.json defines where assets come from. Stock config includes a default archive.org archive and a Retrodriven custom archive; you can switch via Use custom archive or edit JSON.

Types

Example core_specific_archive:

{
    "name": "Spiritualized.2600",
    "type": "core_specific_archive",
    "archive_name": "htgdb-gamepacks",
    "files": [
      "@Atari 2600 2021-04-06.zip"
    ],
    "enabled": true,
    "one_time": true
}

Internet Archive credentials

Some items need login. Add to pupdate_settings.json:

"credentials": {
  "internet_archive": {
    "username": "me@something.com",
    "password": "12345"
  }
}

CLI commands and parameters

  menu                     Interactive main menu (default)
    -p, --path                Absolute path to Pocket install / SD root
    -s, --skip-update         Open menu without checking for pupdate self-update

  fund                     List sponsor / funding links
    -p, --path
    -c, --core                Optional core id filter

  update                   Run Update All (respects settings)
    -p, --path
    -c, --core                Optional single core id
    -r, --clean               Clean reinstall cores

  uninstall                Remove a core
    -p, --path
    -c, --core                Required
    -a, --assets              Also remove Assets/{platform}/{core}

  assets                   Download assets only
    -p, --path
    -c, --core                Optional core id

  firmware                 Check firmware
    -p, --path

  images                   Download a platform image pack
    -p, --path
    -o, --owner               Repo owner
    -i, --imagepack           Repo name
    -v, --variant             Optional variant

  instance-generator       Run instance JSON generation (PC Engine CD workflow)
    -p, --path

  backup-saves             Backup Saves & Memories
    -p, --path
    -l, --location            Backup folder (required)
    -s, --save                Persist location in config for Update All

  gameboy-palettes         Download Game Boy palette pack
    -p, --path

  pocket-library-images    Download Pocket library images
    -p, --path
    -n, --name                Catalog entry id (omit for Spiritualized archive)
    -i, --info                Show details for -n
    -l, --list                List catalog ids (Spiritualized = no -n)

  pocket-extras            Install a Pocket Extra by id
    -p, --path
    -n, --name                Extra id (required for install)
    -i, --info                Show details for name
    -l, --list                List all extras

  display-modes            Apply **recommended** display modes (same as curated menu action)
    -p, --path

  prune-memories           Prune old save states (Memories)
    -p, --path
    -c, --core                Optional core id

  analogizer-setup         Run Analogizer setup wizard
    -p, --path
    -j, --jotego              Jotego-specific wizard

  clear-archive-cache      Clear cached archive downloads (same as Pocket Maintenance → Clear Archive Cache)
    -p, --path
    -y, --yes                Required confirmation flag

  update-self              Check for pupdate updates

  help                     Help for a verb

  version                  Print version

Examples

pupdate -p /path/to/sdcard/
pupdate update -c boogermann.bankpanic
pupdate assets -c jotego.jtcontra
pupdate images -i pocket-platform-images -o dyreschlock -v home

Jotego beta cores

Place jtbeta.zip from Patreon on the root of the SD card (exact name). Update All copies the beta key into the folders that need it. Do not rename the file.

Auto-fetching jtbeta.zip (optional)

Pupdate can download the latest jtbeta.zip for you. Manual placement (putting jtbeta.zip on the SD root yourself) always wins — auto-fetch only runs when no manual key is present. Two optional sources are supported; if both are enabled, GitHub is tried first and Patreon is the fallback.

Option A — GitHub (recommended):

Jotego distributes jtbeta.zip via a private GitHub repo (jotego/jtbeta). Per Jotego’s own Beta Files FAQ, access is granted to GitHub Sponsors of Jotego — and since Jotego’s GitHub Sponsors page accepts Patreon as a payment route, existing Patreon patrons can get the same sponsor status (and therefore the repo invite) by linking their Patreon to their GitHub account.

  1. Make sure you have an active paid Jotego subscription. Either:
  2. Accept the invite to jotego/jtbeta once it arrives.
  3. Create a GitHub Personal Access Token with read access to private repos (classic PAT with repo scope, or a fine-grained PAT with Contents: Read on jotego/jtbeta).
  4. Set github_token in pupdate_settings.json to that PAT.
  5. Enable Auto-fetch Jotego jtbeta.zip from GitHub in the Settings menu.

Option B — Patreon session cookie (experimental, fallback):

Experimental and flaky. This uses Patreon’s undocumented frontend API with your browser session cookie, not a supported public API. Cookies expire (usually in weeks, sooner if you log out or clear cookies), and Patreon can change response field names without notice. Prefer Option A if you have any way to. Treat this as a best-effort fallback, not a stable integration.

pupdate will never use your Patreon session cookie for anything other than making HTTP requests to patreon.com to locate and download jtbeta.zip (and, if you run the diagnostic, to verify your login and Jotego membership). It’s stored locally in pupdate_settings.json and is never sent to any third party, telemetry endpoint, or server that isn’t patreon.com.

  1. Open https://www.patreon.com in your browser and log in.
  2. Open DevTools (F12 or ⌘⌥I) → Application (Chrome/Edge/Brave) or Storage (Firefox) → Cookies → https://www.patreon.com.
  3. Copy the value of the session_id cookie.
  4. In pupdate: Pocket Setup > Set Patreon Session Cookie, paste the value.
  5. Enable Auto-fetch Jotego jtbeta.zip from Patreon in the Settings menu.

Use Pocket Setup > Test Patreon Session Cookie to verify the cookie works and whether your account is currently a Jotego patron.

Notes:

Analogizer setup

Pocket Setup → Analogizer Config — choose Standard (RndMnkIII) or Jotego flow. For problems with generated files, ask the core author. Supported cores.

Coin-Op Collection beta cores

  1. Enable Coin-Op Collection Beta Access in Settings.
  2. On the next Update All, enter the Patreon email tied to your subscription (or set it under Pocket Setup → Set Patreon Email Address).
  3. Later runs can refresh the license automatically.

Troubleshooting

Developers

Submitting new cores

openfpga-cores-inventory / analogue-pocket

Credits

Thanks to neil-morrison44 — this project builds on his original script.

With special thanks to
Michael Hallett · RetroDriven · dyreschlock · espiox

Other updaters