Link
docs
Search

norns: help

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 help@monome.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.

sections

replacing parts

wifi nub

If you have lost your nub, you can purchase a new one here or email help@monome.org 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.

charger

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.

battery

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 help@monome.org for a replacement (15 USD, shipping included, only US).

encoders

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 help@monome.org 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.

storage

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.

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 getting very close to your wifi router. Bad signal can make it seem nonfunctional.

  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 help@monome.org 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 help@monome.org 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: how do I clear a currently running app/script?

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.

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

DUPLICATE ENGINES

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).

To typically solve this, connect via wifi and open maiden. Type ;restart into the maiden matron 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:

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: ack and 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 help@monome.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 dust folder.

LOAD FAIL

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.

SUPERCOLLIDER FAIL

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 help@monome.org.

FILE NOT FOUND

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 (02/18/2020) 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 norns200218.tgz
cd 200218
./update.sh
  • Upon completion type sudo shutdown now.

fresh install

nb. these instructions apply only to stock norns. If you have a norns shield, please see the github documentation for the latest shield image and troubleshooting help.

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.

Steps:

  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

change passwords on norns

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 we user.

login / ssh

To change the login/ssh password for user we, log in to the norns via ssh. The command

passwd

will prompt you for the current and new password.

Samba

The 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.

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):

_norns.screen_export_png("/home/we/dust/<FILENAME>.png")

Use SMB or SFTP to connect to norns and download the PNGs you just created from the dust folder. 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, download this bash script and place it in the same folder as your downloaded screenshots. In terminal, cd to the folder and execute:

./norns-convert_screenshots.bash

That will clean up all the PNGs to render how they do on the norns screen.

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

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.png

what are the audio input/output hardware specs?

Codec

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.

Inputs

The input jacks are configured for balanced or unbalanced. Input impedance is 10k.

Outputs

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.

Headphone driver

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.

can I plug modular signals into norns directly?

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.

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, 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.