Skip to content

The Clerk: RETIRED

Clerk has been retired! All players should use Foam from here on out.

The Clerk is a browser-based utility for updating Atrium's firmware, modifying its settings, and loading & saving patches! It works on any Chromium browser (eg. Chrome, Edge, Brave, Opera, etc).

Visit the Clerk at https://atrium.whimsicalraps.com/clerk

The Clerk hosts its own documentation on its dedicated site, so we won't repeat that here, but perhaps its helpful to note that we can use it to manage:

  • spectre's filtering
  • touchplate sensitivity
  • lighting brightness
  • loading & saving patches
  • firmware updates

Offline Access

The Clerk is a humble worker, operating as a static website served from a single folder on our server. Besides fetching the latest firmware on-demand, it has absolutely no dependencies or dynamic content; this means we can simply save the website in full and use it as an offline utility.

Simply load the Clerk in your Chromium browser (while online) and Save Page As..., which will download two files to your chosen location: Clerk.html and a Clerk_files folder. Just keep them both in the same location and open Clerk.html whenever you need offline access to its functionality.

It's good practice to refresh your downloaded Clerk files whenever there's a new Atrium update, as features for both tend to release simultaneously.

If you save a firmware's .dfu file from Atrium's firmware repository, you can also use Clerk to update while offline using its Update from File workflow.

Atrium: System Modes

Atrium (running v1.2.0 or later) has three system modes:

  • runtime: this is the main Atrium instrument
  • loader: this is v1.2.0+ bootloader, which allows you to perform updates
  • system DFU: the original bootloader, still accessible to allow updates to the loader in the future

Once v1.2.0+ is installed, Clerk takes care of switching from runtime to loader when you begin the update process, but if you need to manually access the loader, hold tap and gesture while powering up Atrium.

Some notes on usability:

  • In Clerk, the loader will appear as "Atrium Bootloader" instead of "DFU in FS Mode". Updates via the loader are substantially faster than from the system DFU.
  • The first light in the gesture lightstrip will pulse indicating it is ready to update.
  • When an update begins, the gesture lightstrip will fill with dim blocks (firmware is being erased), then a bright light will fill it from left to right (firmware is being written). On completion, Atrium will return to the runtime.
  • See which version Atrium is on without a computer by reading the numbers in the phase window.
  • To exit the loader without updating and return to runtime, press load + clear.
  • The loader will play a small composition while updating, with the volume knob functioning as normal.

If you need to access to system DFU, you can jump there from the loader by holding clear for 3 seconds. The phase meter will count you down from 3, and you will see the letters dFU across the light windows. You can then use Clerk to update the loader as well as the runtime.

Troubleshooting

MacOS

If Atrium is not successfully populating as a device once you've clicked Clerk's connect button, ensure that you have allowed Atrium to connect to your Mac via the system pop-up:

If Atrium is not successfully populating as a DFU device once you've clicked Update to Latest or Update from File, it's likely because MacOS has denied Atrium's DFU mode from registering as an 'allowed' device. Ensure that you have additionally allowed Atrium to connect to your Mac via the second system pop-up:

Once you Allow the device, you will need to click Update to Latest again to actually select it (DFU in FS Mode) from the pop-up.

If at any point you accidentally pressed Don't Allow, simply reconnect Atrium via USB and MacOS should prompt for your approval again.

Windows

v1.2.0+ / loader mode

If you're updating from v1.2.0, Clerk will automatically place Atrium into loader mode after you click Update to Latest or Update from File. If you do not see Atrium Bootloader in your browser's popup window, it's likely because Windows does not already have a generic WinUSB driver installed for Atrium's loader mode. In this case, manual assignment is necessary:

  • Download Zadig and run the program
  • If Atrium is not yet in loader mode, then please connect to it via Clerk and click Update to Latest (or Update, if updating from a file) to put it into loader mode
    • You can also hold Atrium's black gesture key and tap while powering to enter loader mode
  • Once Atrium is in loader mode, it should populate in Zadig's Device dropdown as Atrium Bootloader
    • Don't see it? Click Options > List All Devices
    • DO NOT select any other devices which are not Atrium Bootloader
  • With the Atrium Bootloader device selected in Zadig, ensure that the destination driver is WinUSB (v6.1.7600.16385)
  • Once the above is verified, click the Install Driver button in Zadig:

  • Zadig will now install the driver, which may take some time. When it's completed, it will alert you that "The driver was installed successfully" and you'll see that the WinUSB driver was assigned to the Atrium Bootloader device:

  • Back at the Clerk, click Update from latest (or Update, if updating from a file) again and you should be able to select the Atrium Bootloader device from the pop-up
    • It might also populate as Atrium Bootloader - Paired
  • Once the update is complete, feel free to close Zadig – you should not follow this workflow for future updates, as your Windows machine now has a driver assigned to Atrium's loader mode!

pre-v1.2.0 / system DFU mode

If you're updating an Atrium that does not already have v1.2.0+ installed, or you are updating a v1.2.0+ Atrium using the system DFU mode for the first time, you will need to manually assign a generic WinUSB driver installed for Atrium's DFU mode:

  • Download Zadig and run the program
  • If Atrium is not yet in DFU mode:
    • pre-v1.2.0: connect to Atrium via Clerk and click Update to Latest (or Update, if updating from a file) to put it into system DFU mode
    • v1.2.0+: connect to Atrium via Clerk and click Update to Latest (or Update, if updating from a file) to put it into loader mode, then hold clear for three seconds to enter system DFU mode
  • Once Atrium is in DFU mode, it should populate in Zadig's Device dropdown as DFU in FS Mode
    • Don't see it? Click Options > List All Devices
    • DO NOT select any other devices which are not DFU in FS Mode
  • With the DFU in FS Mode device selected in Zadig, ensure that the destination driver is WinUSB (v6.1.7600.16385)
  • Once the above is verified, click the Install Driver button in Zadig:

  • Zadig will now install the driver, which may take some time. When it's completed, it will alert you that "The driver was installed successfully" and you'll see that the WinUSB driver was assigned to the DFU device:

  • Back at the Clerk, refresh the page and go through the update steps again and you should be able to select the DFU in FS Mode device from the pop-up
    • It might also populate as DFU in FS Mode - Paired
  • Once the update is complete, feel free to close Zadig. You have successfully assigned a driver to Atrium's system DFU mode, but note that you will likely need to follow the v1.2.0+ / loader mode steps listed above when you update next time.

Linux

If Atrium is not appearing as a DFU device once you've clicked Update to Latest or Update from File, it's likely because of a security issue which requires adjusting udev rules.

In your terminal of choice, create a udev rules file for Atrium, and open it for editing, by executing:

sudo nano /etc/udev/rules.d/49-atrium.rules

Into it, write:

SUBSYSTEMS=="usb", ATTRS{idVendor}=="cafe", ATTRS{idProduct}=="df11", MODE:="0666"

Exit and save (Control + X, then Y). Reload the udev rules by executing:

sudo udevadm control --reload-rules
sudo udevadm trigger

Physically reconnect Atrium and you should now be able to connect in Clerk.

Update Failure

If a firmware update fails and the extension window displays "f" (for "fail"):

  • Keep Atrium connected to your computer, as it has automatically forced itself back into the loader!
    • If you disconnected Atrium already, that's okay too! Hold tap and gesture while powering up Atrium to enter the loader.
  • Since Atrium is now in loader, the initial connect button workflow is not needed – simply skip ahead to the Firmware Update tab and select either Update to Latest or, if you have a firmware file downloaded, Update from File.
  • You can now simply retry the firmware update, making sure your cable connection is solid & that you keep Clerk's window in view throughout the update.

If a firmware update fails and Atrium only displays a white/blueish light in the little window embedded along the left edge:

  • Wait a minute or two, as Atrium might simply be recalibrating its oscillators – monitor Atrium's audio outputs to confirm. Atrium will return to normal operation after it finishes.
  • If Atrium is not calibrating or does not return to normal operation, disconnect Atrium from power.
  • Hold tap and gesture while powering up Atrium to enter the loader.
  • Since Atrium is now in loader, the initial connect button workflow is not needed – simply skip ahead to the Firmware Update tab and select either Update to Latest or, if you have a firmware file downloaded, Update from File.
  • You can now simply retry the firmware update, making sure your cable connection is solid & that you keep Clerk's window in view throughout the update.

Info

If neither of these cases resolves or describes your trouble, note the colour of the debug light (embedded along the left edge of Atrium) and send a message to support@whimsicalraps.com with as much detail as possible. eg. Which OS is your computer is on? Which browser & what build? Did you "Update to Latest" or "Update from File"? Any other details you can imagine. More info the better!