Axoloti
Main window
The main window manages the connection with the Axoloti board, and also contains
a log of info and error messages.
Patch window
Double click in an empty document ("patch") to create a new object (or press "n").
This brings up the object selector window. In the object selector you can type a name, objects containing the name will appear.
Objects
Objects contain:
- titlebar containing the kind of object
- instance name the name you give it.
Duplicate names in a patch are illegal.
- inlets: colored circles on the left side
- outlets colored squares on the right side
- attributes values that can only be set before running the patch.
- parameters values that can be set before loading the patch and also be modified during a "live" session.
- indicators visualizations of live data from the patch.
Operations on objects (not in Live Mode):
- Objects can be moved by dragging the titlebar.
- Objects can be selected by clicking the titlebar, or dragging a rectange around a group.
- Selected objects can be deleted by pressing delete or backspace.
- Objects can mutate to a different type by double-clicking on the title. Connections and parameters will be preserved. Attributes are not preserved (yet)!
- Instance name can be changed (a double click on the instancename brings up the instance name editor)
- Attributes can be changed
- Parameters can be changed by
- mouse for units
- shift-mouse for sub-units
- arrow-up, arrow-down
- shift-arrow-up, shift-arrow-down
- page-up, page-down
- home, end
- or typing the number followed by enter
- Some parameters have real-world units, displayed left of the dial. For some, multiple conversions are meaningful. Clicking on the real-world unit to alternate between different units. Eg. frequency in Hertz or period time in milliseconds.
- Parameter mapping to MIDI Continuous Controllers: right click on the parameter to assign a MIDI controller. Mapped parameters have a "C" mark right of the dial.
Operations on objects (in Live Mode):
- Parameters can be changed
- No objects can be added/moved/replaced!
Connections
Connections between objects can be made by dragging from an inlet to an outlet or from outlet to inlet.
Connections can be deleted via the pop-up menu (right-click) on inlets or outlets.
Different data types are marked by different colors on the outlets, inlets and wires.
- Red connections are for s-rate (audio-rate, 48000 Hz). The normal range is -64 to 64 units.
- Blue connection points are for k-rate (control-rate, 3000 Hz) fractional numbers. The normal range is -64 to 64 units. Control voltages in modular synthesizer lingo.
- Yellow connections are for k-rate booleans. Gate signals in modular synthesizer lingo.
- Green connections are for k-rate integers (whole numbers). The range is -2147483648 to 2147483647.
- Pink connections are for strings. Mostly useful for dynamic filenames.
connections between different types
- A red output can be connected to a blue input, this will take one out of 16 audio samples.
- A yellow output can be connected to a blue input, this yields +64 units for true, 0 for false.
- A green output can be connected to a blue input.
- A blue output can be connected to a green input, the value is rounded down.
- A pink output must always be connected to a pink input.
A connection that is illegal is drawn as a thick black dashed wire, and ignored.
Execution order
Every object in the patch is executed once in the signal processing loop, at 3000Hz.
Objects are executed in reading order: left to right, top to bottom.
A connection from an outlet to an inlet earlier in the execution order, are buffered.
So feedback topologies are legal, and never result in stack overflows.
Live connection
Engaging live mode generates compilable code from the patch, compiles the code, uploads the binary and starts the binary on the board.
In live mode, only parameters can be changed.
Connections, execution order, location, attributes,... are all frozen.
Currently presets, midi mapping, and modulation can be adjusted in live
mode, but those changes are only reflected until after engaging live mode again.
Keyboard shortcuts
- Arrow keys to move selected objects
- To adjust a focused parameter :
- Up/down arrow keys to increment/decrement by a single units
- Shift-up/down arrow keys to increment/decrement by a tenth of a single unit
- Control-shift-up/down arrow keys to increment/decrement by one hundredth of a single unit
- Control-up/down arrow keys to increment/decrement by 5 units
- Mouse-wheel (also in combination with shift and control) does the same as arrow-up and arrow-down
- Page-up/page down to make coarse adjustments
- Home/end to go to minimum/maximum
- or just start typing a value, followed by enter!
- 'c' to add a comment to the patch
- 'n' to add an object to the patch
Subpatching
To maintain clean patches, it is useful to define an object from a patch.
To do this:
- Create a "child" patch, use inlet, inlet~, outlet, and outlet~ objects to create connections in the resulting object.
- Save this patch.
- Create a new "mother" patch
- Save this patch to the same directory as the "child" patch
- you can use the "child" patch as an object, by entering the patch filename in the object selector (without .axp extension), prefixed by "./".
If you want to modify this object, and propagate the changes:
- select "edit object definition" in the object popup menu
- the "child" patch window opens
- to propagate changes, save the child patch.
- "live" changes are not working in a child patch. Changes are only effective after re-enabling live mode.
Parameters can be propagated to the encapsulating object, right-click on the parameter and select "show on parent".
"Show on parent" parameters are drawn in blue.
Polyphonic Subpatching
A polyphonic subpatch creates an array of the subpatch. Every element in this array is called a "voice".
For playing music, this automatically allocates notes played simultaneously to different voices.
You can obtain the index of the voice with the "voiceindex" object.
Presets
A preset is a set of selected parameters and their new value. To include a parameter to a preset, select the preset index to edit in the toolbar. Then right-click on a parameter and select "include in current preset" in the popup-menu. The parameter will turn yellow. A yellow parameter is not updated live, but indicates that you are adjusting its value in the preset.
Changes to presets are only updated after dis- and re-engaging the live checkbox!
Presets in a sub-patch can be applied only with the "preset" object.
A preset in a "normal" sub-patch only affects the sub-patch.
A preset in a polyphonic sub-patch only affects one voice.
Advanced tricks
Working without hardware
Currently patches do not run without hardware attached.
But you can test compilation. Choose "generate code" in the patch menu, and then "compile code".
Note: by default those menu items are invisible, and show up if you enable ExpertMode in .preferences.xml
Editing code after code generation and before upload
Do not use the "live" checkbox. Choose "generate code" in the patch menu, edit the code in the file "patch/xpatch.cpp", then choose "compile code" in the patch menu, and finally select "upload code".
The edits in the code are of course destroyed when the code generator runs again.
Note: by default those menu items are invisible, and show up if you enable ExpertMode in .preferences.xml
XML copy paste
Copy/paste uses XML in text format in the clipboard. You can copy an object from a patch, and paste it in a text editor, inspect/edit its internals, copy it from the text-editor and paste it into the patch again.
Axoloti core
Normal operation
By plugging in the usb-connection, the board powers up. The power LED should light up immediately. The other LED should flash three times if everything is OK.
Patch binaries are specific to the version of the firmware. If the patch binary is made with a different version of the firmware, Axoloti will crash.
In that case, unplug the sdcard before applying power to Axoloti, or hold button S2 during power-up.
Connections
- The 3.5mm (1/8") mini-jack is a headphone output. Use only for headphones. To connect other equipment, use the 6.25mm connector! This is because the headphone jack is electrically biased at 1.65V.
- The 6.35mm (1/4") jacks are audio in- and output (labeled on the backside of the circuit board).
- The 5 pole DIN connectors are MIDI in- and output (labeled on the backside of the circuit board).
- micro-sd-card (should be FAT formatted)
- mini-usb also serves as the power source. For standalone use, you can use a USB adaptor, or an external USB battery, commercially available for smartphones and tablets. But you need a mini-usb plug, not the micro-USB (more common on tablets and smartphones).
Common problems, errors and solutions
Fatal error: can't create build/obj/chcore_v7m.o: No such file or directory
(or: Fatal error: can't create build/obj/crt0.o: No such file or directory)
Create an empty directory called "obj" in firmware/build. While you're there, also create the directory "lst" in the same place.
fatal error: diskio.h: No such file or directory
unzip chibios/ext/fatfs-0.9-patched.zip to chibios/ext/fatfs
After firmware update the led flashes three times but can't connect
You probably have a "start.bin" file on sdcard that does not match the firmware version.
The solution: unplug Axoloti Core and replug it while holding pushbutton S2 until after the LED flashes three times. This prevents "start.bin" from loading (and crashing). Now it should be able to connect again and overwrite "start.bin" with a new one using the "upload to sdcard as startup" menu.
Alternatively, you can remove the sdcard and erase the "start.bin" file with an sdcard reader.
Or remove the sdcard before powering up the Axoloti Core, then insert the card it again, and use the "Upload to sdcard as startup" command.
Error: "region `SRAM' overflowed by 14760 bytes"
The executable binary code is too big to fit the allocated memory.
Error: "region `CCMSRAM' overflowed by 66780 bytes"
The patch uses too much memory for variables to fit. Delay-lines, echos, RAM tables or sample streaming buffers are the biggest consumers of memory.
The Axoloti program froze up, can I still save my document?
Often yes, after disconnecting the USB cable, the program unfreezes.
The delay/read objects have no units
The knob-setting on the delay/delread objects is the fraction of the actual full delay length of the corresponding delay/write.
So if the delay/read is reading from a delayline of 1024 samples,
the zero position of the delay/read corresponds with zero samples, and the max position with 1024 samples.
Limitations
- 8 presets buttons in the GUI. The actual number of presets in a patch is configurable in patch settings dialog.
- The number of modulation sources and the number of modulation targets per source is configurable in patch settings dialog.
- The patch can use 64kB of on-chip RAM.
- The patch executable code can use 56kB of on-chip RAM.
Known issues
- No undo function
- Modifications of presets are not applied while in live modus, only when entering live modus.
- Midi Controller mapping changes are not applied in live modus.
- Modulation changes are not applied in live modus.
- the size of objects changes depending on ???
- OSX retina screens: radio buttons not drawn correctly?
- Object selector popup does not follow scrolling and misses some shortcuts. Also outside the screen if activated close to the bottom right
- Some limitations are not checked/enforced... (memory usage, number of presets, number of modulation sources/targets)
- if you computer goes in sleep, the connection is stuck. Unplug the board, save your work, quit Axoloti and launch it again.