3.2. Install old Patcher on MacOS


Main window of the Axoloti Patcher.

If you already have the original Axoloti Patcher installed, please skip to step 3. The runtime and Patcher you'd be installing in this guide is the exact same piece of software. Only the Firmware Dir needs to be changed and the ksoloti-objects need to be added to use the Patcher with the Ksoloti Core.

The install process for Ksoloti-legacy is identical to Axoloti with a few extra steps. To reduce size we split the application into two parts, the main Axoloti application, and a runtime which contains other required files. You must download and install both.

If your Ksoloti Core is currently connected via USB, disconnect it now.


  1. Install the runtime. Head to the Axoloti Releases page on Github and download the latest axo_runtime_mac_(version).dmg (at the time of writing: axo_runtime_mac_1.0.12.dmg).

    Open the dmg image and drag the axoloti_runtime folder to your Applications folder.

    Check that you have the correct folder structure:

    • /Applications/axoloti_runtime/platform_osx

    Later OSX/MacOS versions have a quarantine feature that blocks unknown apps from being run. Let's find out if your Mac will block the runtime when you start running it. In a terminal, enter:

    xattr /Applications/axoloti_runtime

    If the command returns the phrase com.apple.quarantine the Axoloti runtime will be blocked as soon as you try to compile a patch in the Patcher. To solve this, run the following command in the terminal:

    xattr -r -d com.apple.quarantine /Applications/axoloti_runtime

    This removes the quarantine extended attributes from everything in the axoloti_runtime folder and makes it usable. There are many ways to do this sort of thing and you may get Apple folks telling you other variants. The method described here seems to work without too much effort.

    The Axoloti runtime is now installed. You will not have to move or edit it unless there is a big update, or you reinstall your OS, etc.


  2. Install the Patcher. From the link in step 1, download the newest axoloti-mac-(version).dmg (at the time of writing: axoloti-mac-1.0.12-2.dmg).

    Open the dmg image and drag the Axoloti app to your Applications folder.

    To start the app, hold down the Control button, click on the app icon (or simply right-click), and select Open from the options menu.

    This will defeat the quarantine from kicking in. You only need to do this once on the first run. Your Mac will remember Axoloti as a recognized app after that and you will be able to start it like any other app.

    While the patcher is being installed, you may get a message prompting you to install "git" or the "developer tools". Click Install. Git will be required for automatic syncing of the object libraries.


  3. The Patcher is now installed. Now we need to link it to the custom ksoloti-legacy firmware. Head to the ksoloti-legacy repository on Github and download the source code as a zip file.

    Extract the file ksoloti-master.zip (or ksoloti-legacy-master.zip, or similar) to a location of your choice. I usually place it in my ~/Documents folder.


  4. Start the Axoloti app you installed in your Applications folder earlier (this is the Patcher). If you haven't done so yet, remember to hold down the Control button, click on the app icon and select Open from the options menu the first time you launch the Patcher.


  5. In the Patcher, open the File menu and click on Preferences... In the resulting window you will see an option called Firmware Dir.

    Click on Select and navigate to the path where you extracted the ksoloti-master.zip from step 3. Then find the subfolder /firmware in the ksoloti-master folder (or similar) and click Open.

    When you're done the Firmware Dir field should read something like [...]/ksoloti-master/firmware. It is important that you point the directory to the [...]/firmware subfolder. Click OK.


  6. Close the Patcher and restart it for the new firmware path to take effect.


  7. Let's do a first test to make sure all the directories are correctly set. Open the Board menu and click Firmware > Compile. There should be a lot of text running across the console and it should end with the message Done compiling firmware. This is good news – everything is set up correctly so far!


  8. We now need to tell the Patcher to fetch the custom ksoloti-objects repository for us. It contains the custom objects so that you can use all GPIO and functions of the Ksoloti Core.

    Open the File menu and click on Preferences... again. In the resulting window you will see a table containing items like “factory”, “home” and “community”. Click on the “+” button to the right of it.

    The “add library” window will appear. This is where we set up the remote address to the ksoloti-objects repository. Enter the following settings:

    Type: git

    ID: ksoloti-objects

    Directory: Click Select and select a folder of your choice. Then, add the string /ksoloti-objects/ to the path in the text field. This will let Git automatically create the folder ksoloti-objects in the folder you have selected. In this example I again chose my Documents folder then added /ksoloti-objects/ to the end of the path. Make sure there is a slash "/" at the end of the path.

    Remote Path: https://github.com/ksoloti/ksoloti-objects.git

    Click Init and confirm. This should create the ksoloti-objects folder in your selected folder and fill it with the custom Ksoloti objects so the Patcher can find and use them. Click OK, and OK again to close the preferences.


  9. Connect the Ksoloti Core board. Your Mac should automatically detect it as a USB device. If you want to make sure, open a terminal and enter:

    ioreg -p IOUSB

    Confirm that there is a device called "Ksoloti Core" in the list.


  10. In the Patcher, click on Connect. You might get a Firmware CRC mismatch warning. This is because the firmware has been updated since your Ksoloti board was shipped. Click Yes.

    The Patcher should update the board automatically. Wait until it is done. When only the green LED lights up steady, you can click on Connect again.


Congratulations, you're done with the tedious setup process and finally ready to open some patches!

As of now, either Axoloti Core or Ksoloti Core can connect to the old Patcher at a time, not simultaneously. This is because the Patcher was not written with supporting multiple boards in mind. If you ever want to revert the Patcher to connect to Axoloti Core, all you have to do is set the Firmware Dir back to /Applications/Axoloti.app/Contents/Java/firmware like in the first screenshot in step 5, then restart the Patcher.

We are working on a standalone Ksoloti version for the Patcher. This will simplify the installation and make it possible to run the original Patcher with your Axoloti Core, and the Ksoloti Patcher with the Ksoloti Core at the same time.