# CDJ-900NXS firmware patcher

Builds a new `C900NXS.UPD` from the official CDJ-900NXS firmware 1.31 with
the mods you choose, for the player's own USB update.

```sh
python cdj900nxs_patcher.py C900NXS.UPD                  # choose in a list
python cdj900nxs_patcher.py C900NXS.UPD --mods cuecolours,hotcuekeys
python cdj900nxs_patcher.py C900NXS.UPD --stock          # the original, to go back
python cdj900nxs_patcher.py --list
```

In the list: **arrow keys** move, **space** ticks or unticks, **a** ticks all
or none, **enter** builds, **q** quits. Ticking a mod ticks what it needs;
unticking one unticks what needs it (`utility` needs `code`, `hotcuekeys`
needs `cuecolours`). A mod with known faults starts unticked.

Before anything is built the patcher shows a disclaimer that must be
accepted by typing `yes` (or with `--accept`, where no one can type): the
mods and the patcher were developed with Claude Code, Anthropic's AI coding
assistant, and are used at your own risk. Terminals that cannot pass single
keys (Git Bash's mintty, a pipe) get a numbered list instead. The result goes
to `out/<date>-<mods>/C900NXS.UPD` with a `report.txt` of every check.

## What it guarantees

- **Only the original file is accepted**: SHA-256
  `e96bca7d1ac983985992a8e5fa7813e1ebf04bef514e0c6cfd0a8375f667f7f9`, and the
  1.31 application inside it is checked too.
- **Only the main application is replaced.** The boot loader and recovery
  loader (MAIN's records below flash 0x40000), MAIN's S0 header and S7 entry
  records, and the DRIV and PANL sections are copied from the original byte
  for byte. Before anything is written the finished file is read back and
  checked: every section CRC and S-record checksum; DRIV and PANL equal to the
  original; MAIN's header equal but for its version label, application-only
  mode kept; every boot loader and recovery record and byte equal; no record
  past 0x7E0000; the packed application's checksum; and the application,
  unpacked the way the boot loader does it, equal to the patched one.
- **Labelled 1.32**, so that the player's updater does not skip the update as
  the version it already has. The application still reports 1.31 (as
  arnoldasr's builds do). `--stock` gives the original firmware with only that
  label changed: three bytes differ from the official file (the digit and the
  section CRC), exactly as arnoldasr's back-to-stock file, which installed on
  his test player.

Checked in the emulator: both the `--stock` file and one with every mod were
written into an emulated flash and booted through Pioneer's own boot loader,
which unpacked and started them.

## Mods

From the emulator checkout `../CDJ900NXSVirtual` (`--repo` for another place):
`mods/patch_cdj900nxs.py` and the mods next to it.

| mod | what it does |
|---|---|
| `code` | arnoldasr: BPM with two decimals, two-line phase meter, RGB waveform |
| `utility` | arnoldasr: UTILITY > PHASE METER switch (needs `code`) |
| `overview` | arnoldasr: overview waveform colour gradient |
| `beatjump` | TRACK SEARCH jumps 1/2/4/8 beats, UTILITY > BEAT JUMP (known faults on a player, see Risk) |
| `cuecolours` | memory cues in their rekordbox colours, hot cues shown |
| `hotcuekeys` | hot cues A-E on the BEAT DIVIDE keys (needs `cuecolours`), see below |

`hotcuekeys`: UTILITY > HOT CUE KEYS ON; then QUANTIZE pressed briefly
switches the hot key mode (HOT KEYS box beside QUANTIZE), held it is
QUANTIZE. In the mode the BEAT DIVIDE keys 3/4, 1/3, 1/2, 1/4, 1/8 are hot
cues A-E:

- press: jump to the hot cue and play (from pause too);
- hold 0.5 s or longer, then let go: back to the hot cue, standing (gate);
- an empty key held 0.8 s while paused: a hot cue there;
- DELETE held, a key pressed: its hot cue deleted (DELETE alone is DELETE);
- LEDs: off without a hot cue, dim with one, two bright blinks when pressed.

Hot cues set or deleted live until the next track load; nothing is written
to the USB stick. As with CALL, the CUE point moves to the hot cue.

arnoldasr's mods need his repository checked out in
`../CDJ900NXSVirtual/mods/cdj900nxs/upstream` (it has no licence, so it is
not copied here); without it they are greyed out.

## Risk

Nothing here talks to a player; you copy the file to a FAT32 USB stick and run
the update yourself. Our mods were developed with Claude Code in an emulator.
On a player: `beatjump` jumped off the grid and, after a few jumps, reported a
corrupted file and needed a restart; it is being reworked. `cuecolours` and
earlier versions of `hotcuekeys` ran on a player. Recovery from an
application that crashes at start-up has not been tested by anyone. Keep the
`--stock` file at hand.

## Tests

```sh
CDJ900NXS_UPD=/path/to/C900NXS.UPD python -m pytest test_patcher.py
```