- First a quick, printable introduction.
- Studies is a series of tutorials for creating scripts.
- Script reference
Current version at github.
The mini-USB plug provides power and charges the internal battery. Use the cable and power supply provided. (The included supply supplies 2A via USB connector.)
Hold K1 for three seconds.
Be still, and norns will awaken.
There’s a small light near the power plug. ORANGE means power. WHITE means disk access.
On the bottom of the norns there is a tiny push switch that will hard power-off the device. For general shut down use the sleep menu function. This fully turns off the norns with a proper software shutdown. Use the bottom switch only if something in software went wrong.
A changing melody will play.
E1 changes the mode. K1+? means hold K1 then push ?.
- E2 navigates position, E3 changes position.
- K2 toggles the sequence to edit. K1+K2 clears all steps.
- K3 morphs the current sequence. K1+K3 randomizes.
- E2/E3 set loop length.
- K2 resets to play to zero. K3 jumps to random position.
- E2/E3 adjust selected parameter. K2/K3 move selector.
- E2 adjusts BPM. K1+E2 change division.
- E3 changes root note. K1+E3 selects scale.
(bonus: try plugging in a grid.)
Tap K1 quickly to toggle between PLAY and OTHER.
You are now at HOME.
In OTHER mode:
- E1 moves between pages.
- E2 scrolls up/down.
- K2/K3 move back/forward.
At HOME press K2 to toggle additional system information display.
Explore the collection of scripts. Selecting a script will show a description. Forward again will run the script. The play screen will return upon running. Quickly tap K1 to toggle between PLAY and OTHER.
- AUDIO - Like the parameter list, but for the global audio settings. Includes output and input levels, headphone gain, aux send (reverb), and insert (compression). See the AUDIO section below for details on the parameters available.
- DEVICES - This is a list of connected USB hardware with their associated port number. Most scripts address port 1. See norns study 4 for a scripting guide to multiple ports. This section lets you re-assign connected devices to specific ports.
- WIFI - Networking settings. Requires USB WIFI interface. See CONNECT.
- UPDATE - Checks for updates. Internet connection required. See UPDATE.
- RESET - Quickly resets the audio system.
Powers down cleanly, saving current state.
Scripts can define their own parameters. Note that some scripts may have no parameters.
- E2 scrolls.
- E3 changes values. Hold K3 for fine tuning.
HOLD K1 to access parameter set saving and loading:
- E3 scrolls set number (0 is default, with 1-99 available).
- K2 loads the selected set.
- K3 saves the set to the selected position.
Enable MIDI-mapping with E3 while the MIDI-map item is selected. Release K1 to return to the Parameter list, but now you see MIDI CC assignments. Push K3 to enable MIDI-learn, whereupon the next incoming MIDI CC will be mapped to this value.
Get out of MIDI-mapping mode by holding K1 and toggling off.
On this page you can record and play directly to and from disk.
K2 toggles focus between REC and PLAY.
- K3 to arm recording.
- K3 again to start.
- K3 again to stop.
- K3 loads file.
- K3 again to start.
- K3 again to stop.
PLAY expects stereo 48khz files. WAV, AIFF and other uncompressed header / sample formats supported by libsndfile will work (including raw). FLAC also.
Mixing and VU display happens here.
- K2/K3 to change selection, which is highlighted.
- E2/E3 modify the respective highlighted levels.
Audio routing is shown below:
Control of various audio parameters happens in SYSTEM > AUDIO. Note that the topmost levels are also controlled via the LEVELS page.
|output||[-inf, 0] db||output level|
|input||[-inf, 0] db||input level|
|monitor||[-inf, 0] db||monitor level (input mix to ouput)|
|engine||[-inf, 0] db||engine level (ie, supercollider)|
|softcut||[-inf, 0] db||multivoice sampler level|
|tape||[-inf, 0] db||tape playback level|
|monitor mode||[MONO, STEREO]||MONO = mix input 1 and 2 to both channels|
|headphone||[0, 60]||headphone gain|
|reverb||[ON, OFF]||reverb state|
|rev engine input||[-inf, 12] db||engine input to reverb|
|rev cut input||[-inf, 12] db||softcut input to reverb|
|rev monitor input||[-inf, 12] db||monitor input to reverb|
|rev return level||[-inf, 12] db||reverb return level|
|rev pre delay||[20, 100] ms||delay before reverberation|
|rev lf fc||[50, 1000] hz||crossover frequency between low and middle bands|
|rev low time||[1, 32] s||time to decay by 60dB in low band|
|rev mid time||[1, 32] s||time to decay by 60dB in mid band|
|rev hf damping||[1500, nyq] hz||frequency at which high band decay time is 1/2 of mid band decay time|
|compressor||[ON, OFF]||compressor state|
|comp mix||[0, 1.0]||dry/wet mix. 0 = dry, 1 = wet|
|comp ratio||[1, 20]||compression ratio: for each N dB increase in input level above threshold, output level increases by 1dB|
|comp threshold||[-100, 10] dB||amplitutde above which the signal is compressed|
|comp attack||[1, 1000] ms||time constant (1/e smoothing time) for compression gain to exponentially approach a new lower target level|
|comp release||[1, 1000] ms||time constant (1/e smoothing time) for compression gain to exponentially approach a new higher target level|
|comp pre gain||[-inf, 30] db||gain pre compression|
|comp post gain||[-inf, 30] db||gain post compression|
Scripts can be created and edited using a web browser when norns is connected to a network. These scripts will appear in the SELECT list for later play.
The WIFI nub must be inserted before starting.
To connect to your local network router:
- Navigate to SYSTEM > WIFI.
- Select ADD.
- Choose your network from the list displayed.
- Enter the password. E2 toggle between top and bottom row, E3 scrolls character, K3 selects character. Select OK when complete.
- With success, you should be assigned an IP address shortly after.
If you do not have access to a router, you can turn the norns into a WIFI hotspot. This will create a new network which you can then connect to with your computer:
maiden is the web-based editor for norns.
Point your web browser at
norns.local to see the maiden interface. If the site is not found, try connecting directly to the IP address shown on the norns screen, for example:
The interface is arranged into a left sidebar FILE navigator and a right split editor, where the top is the EDITOR and the bottom is the REPL (read-eval-print-loop).
This panel lets you select the text you’re editing in EDITOR.
There are top bar icons for various actions: New, Delete, Duplicate, New Folder, and Rename.
This is where you can edit the selected script.
To the right there is a bar with two icons: disk is SAVE and PLAY will run the current script.
The editor can be configured for various modes (default, vim, emacs) in addition to tab size and light/dark mode. Click the gear icon at the bottom left of the screen.
Messages are printed in the bottom panel. There are two tabs: matron is the main lua environment, and sc is supercollider which is the engine environment.
You can use the bottom prompt to type commands which will be interpreted by the system. For example:
will display the expected message in the window above.
The clear icon to the right will clear the current messages.
If you need to restart the matron/crone environment for any reason (ie, the menu system is not accessible), you can issue a command via the REPL:
This will disconnect maiden, but once matron has restarted you can reconnect.
The bottom left ? icon can be used to navigate to the onboard programming reference.
You can manually open the API reference at
Also see the general reference.
You can delete and rename files via maiden. But you’ll need to copy files between your computer and norns.
File management is best achieved via SFTP, so you’ll need to first connect norns to your laptop via WIFI. Use an SFTP client (such as Cyberduck) to connect to the IP address shown on the norns screen.
See this guide for further details.
Upon logging in you’ll be in the home folder which is
dust is the folder which contains everything we need. Here’s the layout:
dust/ audio/ -- audio files tape/ -- tape recordings ... code/ -- contains scripts and engines awake/ mlr/ ... we/ data/ -- contains user data created by scripts awake/ -- for example, pset data
If you want to make a backup of your scripts, psets or other data simply make a copy of the
dust directory in
/home/we via SFTP.
Restoring from this backup is as simple as copying this directory from your computer back to the
/home/we/dust directory on norns.
When connected via WIFI you can SSH into norns at the IP address shown in SYSTEM.
Without WIFI, you can connect to norns via USB-UART by connecting the power cable to your computer. On Mac/linux do:
screen /dev/tty.usb(tab) 115200
(tab) appears hit TAB to autocomplete the serial number. Login is the same as above.
Browse the Library to see projects created and contributed by various people.
These project pages have information and a download link. Download a file, unpack into a folder, and then move this folder over to the
dust/code/ folder using SFTP. It’ll show up in the SELECT list.
The norns ecosystem was created with community as a focus. The exchange of ideas leads to new ideas.
Create a new thread in the Library.
You’ll be able to attach a .zip file containing your project folder.
Be sure you include information at the top of your script to help future users:
-- scriptname: short script description -- v1.0.0 @author -- llllllll.co/t/22222
That last line is a link back to the thread number. There’s a chicken-egg situation with starting a thread and uploading the project, so you may want to edit and upload your project just after creating a thread.
Alternatively you can host your project as a github repository by simply cloning your project into the
dust/code/ folder. We’re working on infrastructure to integrate more closely with
git, but in the meantime we suggest using
ssh to manage this. In the project thread you can then link to a master download or most recent release.
Updates to the core norns software can be installed easily via the SYSTEM menu. You must first be connected to the internet via wifi and have at least 400M free disk space. If a new version is available you will be prompted to continue installing. Audio will be disabled during this time. Note that the download time may be a few minutes, have patience. Upon completion you’ll be notified of success or failure, then the unit will shut down after confirmation.
If you are running 181101 or earlier you’ll need to first upgrade to 190405 using the old system.
- Download and copy update file to a FAT-formatted USB drive
- Insert the disk to norns and power up.
- Connect via serial (see instructions above).
- Copy file to
sudo cp /media/usb0/*.tgz ~/update/
- Unpack and run update:
cd ~/update tar xzvf norns190409.tgz cd 190409 ./update.sh
- Upon completion type
sudo shutdown nowto shut down.
ERROR: AUDIO ENGINE
If norns shows
ERROR: AUDIO ENGINE chances are there’s a problem with duplicate SuperCollider classes.
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:
ERROR: duplicate Class found: ‘Engine_Some’ /home/we/dust/code/somescript1/lib/Engine_Some.sc /home/we/dust/code/somescript1-copy/lib/Engine_Some.sc ERROR: There is a discrepancy.
Remove one of the offending scripts/classes and either completely restart norns or execute
;restart again from maiden and all should be good again.
The community forum has various informative threads. Please join us!
Check the known bugs list for problems and solutions.
If you’re experiencing hardware problems contact email@example.com and we can help right away.
Norns is the result of generous contributions by many people, and the ecosystem continues to evolve. We welcome discussion and code to help further the goal of an open, dynamic instrument creation platform. Check out the github repo.
We’re also always looking for help with documentation, if your skills include design, instruction, or proofreading. Collective efforts have created numerous exceptional projects over the years, and there’s more to a project than just code!
matron (control system) and
crone (audio system) were created by @catfact.
maiden (editor) was created by @ngwese. Each grew with contributions from @artfwo, @jah, @simon, @rv, @pq, @markwheeler, and many others.
norns was initiated by @tehn (monome).