norns: help


replacing parts

wifi nub

If you have lost your nub, you can purchase a new one here or email for a replacement (10 USD, shipping included, only US).

If you have experienced signal strength issues and wish to replace your WiFi dongle completely, you may wish to purchase a high gain antenna adapter.


The charger that comes with norns is GEO151UB-6020 and its power specs are 2A / 5.25V. A direct replacement can be purchased from Adafruit.


Before you purchase a new battery, please consider that your norns may not be reporting battery performance accurately. To test, fully drain the battery and then charge it fully.

If performance does not improve, then a direct replacement can be purchased from Adafruit or by emailing for a replacement (15 USD, shipping included, only US).


On early batches of norns, some users have reported that the encoder values are “jumpy”. To verify that your encoders are affected, please perform this simple test:

  • navigate to the LEVELS page
  • turn a level all the way up and continue to turn the encoder
  • if the level jumps and does not remain at maximum, then you might want to replace that encoder

We are still working to identify if this is related to our assembly house or if the actual OEM parts are flawed. The fix is incredibly straightforward if you have access to a soldering iron. While we can provide fixes in-house, shipping back and forth has a great deal of environmental impact that we’d love to help avoid. So, please consider DIY’ing and email us at if you have any questions or trepidations about the DIY process.

Replacement encoders can be purchased from Octopart.

Please reference this step-by-step video detailing the fix.

wifi troubleshooting

nb. If you are not actively using the wifi nub, it’s best not to keep it plugged in. It uses a lot of power, draining both battery and system resources.

If you are consistently unable to connect your norns to wifi through the ‘Connect’ steps outlined here, please perform the following steps:

  1. Try plugging the wifi nub into a different USB slot on norns and perform a standard reboot.

  2. Plug the wifi nub into a non-norns computer (laptop/desktop ; MacOS/Windows/Linux) and confirm that the nub functions as expected. If your nub is defective, please email for a replacement

  3. If you are prompted to update the nub’s drivers, please do so. Even if there are no updates available, sometimes the simple task of searching for an update resolves connectivity issues. When this process completes, plug the nub back into norns.

  4. If norns is still unable to connect to wifi, connect the power cable to your non-norns computer and follow the USB-UART steps outlined here. Once you perform this serial login, try executing nmtui for a graphical interface of the wifi utilities, which may have better luck connecting to a network:

  5. If you are still unable to connect, please email with the following information:

    • Whether your nub was able to successfully connect with a non-norns computer
    • Screenshots of the terminal screens in step 4
    • Your router config (WPA, WEP, etc)

help: how do I add/update apps on my norns?

As of 10.28.2019, maiden (the web-based editor built into norns) now features a project manager to help facilitate project discovery, installation, and upgrades.

If you are updating a project through the project manager that was not installed by using the project manager, you will receive an error that the project cannot be found in the catalog. Please delete the previously installed version and reinstall through project manager, which establishes the necessary git files for future updates.

lines also has a dedicated Library for projects tagged norns. In each project’s thread, you’ll find in-depth conversation as well as performance examples and tutorials. Projects for norns are primarily built and maintained by the lines community, so any questions/trouble with a specific project should be directed to its thread.

help: I’ve deleted the code folder!

getting the code folder back

  1. Download Cyberduck – this is an app that will connect to your norns and show its file system like it’s a standard computer.
  2. Follow these instructions to connect to norns through Cyberduck.
  3. After you connect to norns through Cyberduck, double click the dust​ folder and you should see audio​ and data.
  4. In Cyberduck, click ‘Action’ and ‘New Folder’. This will create a new folder alongside the other two. Name this folder code​.
  5. Keep this window open for the next phase!

restoring apps into the code folder

  1. Download we, which is a collection of engines from monome.
  2. Unzip the folder, which will be named we-master​.
  3. IMPORTANT: Rename this folder we​.
  4. Drag the newly named we​ folder into the code​ folder you made in the previous section’s step 4.
  5. You have now install the standard engines! Please reference the “how do I install/update an app onto my norns?” section for help populating your code folder with community apps.

error messages


Supercollider fails to load if you have multiple copies of the same engine (.sc files) inside of dust (the parent folder for the projects installed on norns).

To solve this, connect via wifi and open maiden. Type ;restart into the maiden REPL at the bottom (the >> prompt).

This will restart the audio components and output their logs. If there’s a duplicate class an error message like the following will be shown:


In this example, the engine is duplicated in two projects: ack and we. Using maiden, you would expand each project’s lib folder to reveal the duplicated After you remove one of the offending engines, execute SYSTEM > RESTART from the norns menu.


This simply means there is an error in the script you’re trying to load.

Connect via wifi and open maiden to see the error message when you again try to load the script.

A common problem may be a missing engine. Check the output for something like:

### SCRIPT ERROR: missing Timber

In this example, the script requires Timber, so go find it in the Project Manager and install it. If you had just recently installed Timber, you need to restart your norns through SLEEP or entering ;restart in the matron REPL.


This indicates that something is wrong with Supercollider, which could be due to various issues.

If you’re able to load maiden, there are two tabs in the main REPL area (above the >> prompt at the bottom of your screen). The first tab is for matron, the control program that runs scripts – the other is sc for SuperCollider. Click into the sc tab and type ;restart into the REPL. That should show you what is going on inside of SuperCollider.

  • You might have a duplicate engine.
  • You might be missing a required engine.
  • If an update was recently applied, it may be necessary to manually re-apply it.
  • If this doesn’t help, you may need to re-flash your norns with a clean image (after backing up any of your data).
  • If this doesn’t fix it, there may be a hardware issue: e-mail


If a newly-renamed script throws a file not found error in maiden, it is likely because the system has not registered the name change – even though you see the new name in the UI. Perform a hard refresh on your browser (how?).

manual / offline update

  • Download and copy update file (12/30/2019) to a FAT-formatted USB drive
  • Insert the disk to norns and power up.
  • Connect via serial.
  • Copy file to ~/update/:
sudo cp /media/usb0/*.tgz ~/update/
  • Unpack and run update:
cd ~/update
tar xzvf norns191230.tgz
cd 191230
  • Upon completion type sudo shutdown now.

fresh install

By far the easiest method to flash the disk image is using etcher. It is available for Linux, MacOS, and Windows.

WARNING: flashing a disk completely erases the contents and replaces it with a clean install. Be sure to first back up any data you have in dust.


  1. Install etcher and get the disk image. Extract the disk image so you have a remaining .img file.
  2. Remove the four bottom screws of the norns.
  3. Plug the norns power into your laptop.
  4. You’ll see a switch through a notch in the circuit board, flip this to DISK.
  5. Run etcher. Select the disk image. Select the Compute Module as the target. Push go and wait for it to finish.
  6. Disconnect USB. Flip the switch back to RUN. Put the bottom back on.

If you prefer the command line see this guide.

back up norns to USB

nb. SFTP through Cyberduck is the most straightfoward way to back up your norns. These instructions are provided for times when you are unable to connect norns to WiFi (no dongle, no network, etc).

First, connect via serial and then insert a USB stick into norns.

  • Make sure the USB stick is detected with ls /media/usb (this should show the contents of the USB stick)
  • If it’s there, copy your dust folder with cp -r /home/we/dust /media/usb
  • Shutdown with sudo shutdown now

taking a screenshot

Capturing a screenshot of your norns can be a helpful tool for creating illustrative documentation or sharing UI ideas.

With your norns powered-on and connected to the same WIFI network as your computer, connect to maiden. Then, execute this line in maiden’s REPL (replacing with something unique):


Use SFTP to connect to norns and download the PNG you just created. You’ll notice the PNG is kinda tiny and the colors are inverted. Let’s fix that with ImageMagick.

With ImageMagick installed on your computer, execute the following (replacing <PATH+FILENAME> with the entire path to your downloaded PNG):

magick convert <PATH+FILENAME>.png -gamma 1.25 -filter point -resize 400% -gravity center -background black -extent 120% <PATH+FILENAME>-m.png

For example: magick convert /Users/dndrks/Downloads/mlr.png -gamma 1.25 -filter point -resize 400% -gravity center -background black -extent 120% /Users/dndrks/Downloads/mlr-m.png

This will clean up the image, make it look just like it renders on norns, and save it as a new file with the same name, but a -m at the end :)

additional a’s to faq’s

  • Imported audio must be 48khz, bit depth is irrelevant.

  • Line noise while usb charge + audio input are both coming from the same laptop (ground loop) can be defeated with an isolator.

  • If a connected MIDI controller is not functioning as expected, it may be due to a known limitation in scripts that do not explicitly allow for MIDI control from channels other than channel 1. Either reassign your MIDI controller to channel 1 or insert this bit of code into a script.

  • norns is not able to send MIDI to a VST or DAW directly over USB. You will need either two USB MIDI dongles or 2host.

  • All grid editions will work with norns, but some apps may be coded for varibright levels that your hardware may not support.

  • norns does not have built-in bluetooth + the OS is not designed to take advantage of bluetooth.