Between this page and the search bar above, you should be able to self-solve most norns troubles that you’d run into.
If you need additional help, we’re here for you! Please send an email to firstname.lastname@example.org using this format:
- What issue did you experience?
- What steps are necessary to reproduce the issue?
- What additional hardware was connected to norns at the time of the issue? This includes controllers, WiFi dongles, external hubs, etc.
- Please attach any output printed in maiden when the issue occurs
If you’re unable to supply concrete steps to reliably reproduce the issue, this will reduce our efficacy. Please understand if we point you to existing resources and ask you to verify additional info.
For support with specific scripts and libraries, please visit lines and search for the script’s thread.
- replacing parts
- wifi troubleshooting
- updating + managing apps
- restoring deleted system folders
- error messages
- updating norns
- backing up norns to USB
- change passwords on norns
- taking a screenshot
- audio input/output hardware specs
- can I plug modular signals into norns directly?
- additional q’s
If you have lost your nub, you can purchase a new one here or email email@example.com 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 firstname.lastname@example.org 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 straightforward if you have access to a soldering iron and some past experience. E-mail email@example.com if you’re not comfortable making the fix and we can help.
Replacement encoders can be purchased from Octopart.
Please reference this step-by-step video detailing the fix.
The Raspberry Pi at the heart of stock norns can be replaced with a CM3+ (Compute Module 3+) for up to 32gb of storage. Just search
raspberry pi cm3+ 32gb to find a retailer.
There is no soldering needed, but you will have to disassemble your norns a bit (the first few minutes of this video details how).
Many thanks to
@mutedial for compiling replacement steps.
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 ‘Network Connect’ steps outlined here, please perform the following steps:
Try getting very close to your wifi router. Bad signal can make it seem nonfunctional.
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 firstname.lastname@example.org for a replacement.
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.
If norns is still unable to connect to wifi, connect the power cable to your non-norns computer and follow the
USB-UARTsteps outlined here. Once you perform this serial login, try executing
nmtuifor a graphical interface of the wifi utilities, which may have better luck connecting to a network:
If you are still unable to connect, please email email@example.com 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)
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.
Press K1 to toggle from PLAY to HOME. Highlight
SELECT and hold K1 – you’ll see
CLEAR in the middle of the screen. Press K3 to clear the currently running script.
- Download Cyberduck – this is an app that will connect to your norns and show its file system like it’s a standard computer.
- Follow these instructions to connect to norns through Cyberduck.
- After you connect to norns through Cyberduck, double click the
dust folder and you should see
- In Cyberduck, click ‘Action’ and ‘New Folder’. This will create a new folder alongside the other two. Name this folder
- Keep this window open for the next phase!
- Download we, which is a collection of engines from monome.
- Unzip the folder, which will be named
- IMPORTANT: Rename this folder
- Drag the newly named
we folder into the
code folder you made in the previous section’s step 4.
- 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
codefolder with community apps.
Supercollider fails to load if you have multiple copies of the same class, which are commonly contained in duplicate
.sc files inside of
dust (the parent folder for the projects installed on norns).
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:
DUPLICATE ENGINES: /home/we/dust/code/ack/lib/Engine_Ack.sc Engine_Ack.sc /home/we/dust/code/we/lib/Engine_Ack.sc Engine_Ack.sc ### SCRIPT ERROR: DUPLICATE ENGINES
In this example, the
Engine_Ack.sc engine is duplicated in two projects:
we. Using maiden, you would expand each project’s
lib folder to reveal the duplicated
Engine_Ack.sc. After you remove one of the offending engines, execute
SYSTEM > RESTART from the norns menu.
If the issue persists or maiden does not report duplicate engines, please email firstname.lastname@example.org. Keep in mind that unless you’re familiar with Supercollider, do not tamper with its internal folder structure. All typical norns functionality can be handled through the maiden project manager or the
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. First always just try rebooting via
SYSTEM > SLEEP.
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 email@example.com.
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?).
- Download and copy update file (200712) to a FAT-formatted USB drive
- Insert the disk to norns and power up.
- Connect via serial.
- Copy file to
sudo cp /media/usb0/*.tgz ~/update/
- Unpack and run update:
cd ~/update tar xzvf norns200712.tgz cd 200712 ./update.sh
- Upon completion type
sudo shutdown now.
nb. you do NOT need to do a fresh install just to update your norns, unless your norns is currently running 181101 (Nov 01 2018’s software) or earlier. to perform a standard update, see these instructions. fresh installing will wipe your norns, so back up any data you need before proceeding.
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
- Install etcher and get the disk image. Extract the disk image so you have a remaining
- Remove the four bottom screws of the norns.
- Plug the norns power into your laptop.
- You’ll see a switch through a notch in the circuit board, flip this to DISK.
- Run etcher. Select the disk image. Select the Compute Module as the target. Push go and wait for it to finish.
- Disconnect USB. Flip the switch back to RUN. Put the bottom back on.
- If you have a norns with a 32gb CM3+ (purchased October 2020 and thereafter), you will need to expand the file storage.
7a. Re-connect USB, power norns up, and connect via serial through a terminal.
sudo raspi-configand enter sleep as the password.
7c. Navigate down to
Expand Filesystemand press OK.
7e. After it’s completed, put norns to sleep.
Use etcher to flash your SD card (nb. use a high quality one. if you have trouble, try a different card)
If your SD card seems a lot more full than it should be, you’ll need to expand the filesystem:
- open a terminal on a computer connected to the same network as your shield
- password: sleep
- navigate to Advanced and hit RETURN
- select expand filesystem and hit RETURN
- lots of activity will happen. when it’s done, power down and reboot. if you get any errors, reboot again.
- if you SSH back into norns and execute
df -h, you’ll see the newly expanded capacity.
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
For security reasons (a device exposed to wifi should not have a widely-known password), you may want to change the default password for the
To change the login/ssh password for user
we, log in to the norns via
ssh. The command
will prompt you for the current and new password.
smb:// remote login password does not automatically change when
passwd changes. Although Samba is a low-security, local network project, it makes sense to set its login credentials to match the newly set user password. This can be done with:
sudo smbpasswd -a we
Re-type your new password and you should be all set.
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 ImageMagick installed on your computer, download this bash script and place it in the same folder as your downloaded screenshots. In terminal,
cd to the folder and execute:
That will clean up all the PNGs to render how they do on the norns screen.
nb. You may need to execute
chmod u+x ./norns-convert_screenshots.bash beforehand, or use
sudo ./norns-convert_screenshots.bash if permission is denied.
If you wish to do this manually, 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>.png
magick convert /Users/dndrks/Downloads/mlr.png -gamma 1.25 -filter point -resize 400% -gravity center -background black -extent 120% /Users/dndrks/Downloads/mlr.png
The audio codec is a CS4720.
The codec is externally clocked with a crystal (for no jitter), and the sample rate is fixed at 48k.
The input jacks are configured for balanced or unbalanced. Input impedance is 10k.
The output jacks are configured for balanced or unbalanced. Output impedance is 590 ohm.
Output from the codec is connected to the headphone driver as well.
The headphone driver is a TPA6130A2. Volume is controlled via i2c with a simple protocol, so no driver is necessary, though I think one exists.
The i2c lines are connected to i2c0.
NO! norns (both stock and shield) has line-level inputs only – sending modular signals, which run very hot, through these inputs may result in damage. Please attenuate your modular signals before sending them into norns with an interface module like Intellijel’s Audio Interface.
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, because you’d be trying to connect two MIDI hosts. One solution is to use two USB MIDI interfaces plugged into one another, or some MIDI devices exist with two USB host ports.
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 currently designed to take advantage of bluetooth.