Skip to content

Commit 0359ed8

Browse files
sntxerrorsntxerror
committed
Update source docs structure
1 parent 8c02d0d commit 0359ed8

18 files changed

Lines changed: 1212 additions & 26 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,9 @@ jobs:
118118
run: pip install mkdocs-material mkdocs-minify-plugin pyyaml
119119

120120
- name: Update navigation
121-
run: python scripts/update_nav.py
121+
run: |
122+
python scripts/update_sections_nav.py
123+
python scripts/update_nav.py
122124
123125
- name: Build site
124126
run: mkdocs build

‎README.md‎

Lines changed: 51 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,65 @@
11
# MICRORACK Documentation
22

3-
Official documentation for the MICRORACK modular synthesizer system.
3+
Welcome to the official MICRORACK documentation. MICRORACK is the most accessible modular synthesizer — a compact, breadboard-based platform for learners, makers, and performers.
44

5-
## Overview
5+
## Quick Start
66

7-
MICRORACK is a compact, affordable modular synthesizer system designed for learners, makers, and performers. This site provides everything you need to build, patch, and integrate MICRORACK modules.
7+
New to MICRORACK? Start here:
88

9-
Visit the live documentation at: **[docs.microrack.org](https://docs.microrack.org)**
9+
1. **[System Setup](setup/)** — Unbox, power up, and make your first sound
10+
2. **[Your First Patch](setup/30-first-patch/)** — A step-by-step guide to your first synth voice
1011

11-
## What's Inside
12+
## Documentation Sections
1213

13-
- **↝ Setup**: Getting started guides and first patches.
14-
- **⎌ Ecosystem**: Detailed information on power, I/O, chassis, and system connectivity.
15-
- **⊶ Modules**: Comprehensive overviews and technical details for all MICRORACK modules.
16-
- **⊾ Specification**: Official mechanical and electrical standards for the platform.
14+
### [Setup](setup/)
15+
Getting started guides and safety information.
1716

18-
## Project Structure
17+
| Page | Description |
18+
|------|-------------|
19+
| [Safety & Orientation](setup/10-safety/) | The "notch rule" and handling basics |
20+
| [Powering Up](setup/20-powering-up/) | Connecting and testing your Power Module |
21+
| [First Patch](setup/30-first-patch/) | Make your first sound in 5 minutes |
1922

20-
This site is built using [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/). It dynamically aggregates content from multiple MICRORACK repositories to ensure the documentation is always up-to-date with the latest module designs and specifications.
23+
### [Ecosystem](ecosystem/)
24+
Deep dive into the MICRORACK platform and its capabilities.
2125

22-
- **Modules**: Sourced from [microrack/modules-test](https://github.com/microrack/modules-test)
23-
- **Specifications**: Sourced from [microrack/specs-test](https://github.com/microrack/specs-test)
26+
| Page | Description |
27+
|------|-------------|
28+
| [Breadboard Architecture](ecosystem/10-breadboard/) | How breadboards work with MICRORACK |
29+
| [Power & Expansion](ecosystem/20-power/) | Voltage rails, current management, multi-board setups |
30+
| [I/O & Patching](ecosystem/30-io/) | Patching, color-coding, module chaining |
31+
| [Chassis & Mounting](ecosystem/40-chassis/) | Enclosure options (AE Modular, Eurorack, DIY) |
32+
| [Compatibility](ecosystem/50-compatibility/) | Connecting to external gear |
33+
| [Use Cases](ecosystem/60-use-cases/) | Patch ideas and configurations |
34+
| [Community](ecosystem/70-community/) | Forum and support resources |
2435

25-
## Contributing
36+
### [Modules](https://modules.microrack.org)
37+
Browse the catalog of MICRORACK-compatible modules. *(Fetched on site build)*
2638

27-
If you find errors or have suggestions for improvement, please open an issue or a pull request in the respective repository.
39+
### [Specification](https://specs.microrack.org)
40+
Open hardware specification for module designers. *(Fetched on site build)*
2841

2942
---
30-
© 2019-2025 MICRORACK | [microrack.org](https://microrack.org)
43+
44+
## Resources
45+
46+
| Resource | Link |
47+
|----------|------|
48+
| **Website** | [microrack.org](https://microrack.org) |
49+
| **Forum** | [forum.microrack.org](https://forum.microrack.org) |
50+
| **Instagram** | [@microrack.synth](https://instagram.com/microrack.synth) |
51+
| **Support** | [support@microrack.org](mailto:support@microrack.org) |
52+
| **GitHub** | [github.com/microrack](https://github.com/microrack) |
53+
54+
---
55+
56+
## Open Platform
57+
58+
MICRORACK is an open platform. Any enthusiast or brand can create and distribute compatible modules.
59+
60+
- **Specification License:** [CERN Open Hardware Licence (CERN-OHL-W)](https://specs.microrack.org/LICENSE.md)
61+
- **Contribute:** Submit modules, documentation improvements, or community designs via GitHub
62+
63+
---
64+
65+
*Built with ❤️ by the MICRORACK team and community.*

‎ecosystem/10-breadboard/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Breadboard Architecture
2+
3+
The breadboard is the "canvas" of the MICRORACK system. Understanding how it works is key to building complex patches and expanding your system.
4+
5+
## How Breadboards Work
6+
7+
A standard breadboard consists of:
8+
9+
| Component | Description |
10+
|-----------|-------------|
11+
| **Terminal Strips** | The main area where modules are inserted. Organized in vertical columns of 5 connected points. |
12+
| **Power Rails** | The horizontal rows at the top and bottom (marked with + and – or red and blue lines). |
13+
| **Center Gap** | The divider that separates the two halves of the terminal strips. |
14+
15+
### Recommended Breadboard Sizes
16+
17+
| Size | Contact Points | Modules | Best For |
18+
|------|----------------|---------|----------|
19+
| **830-point** | 830 | 8-12 | Standard setups |
20+
| **400-point** | 400 | 4-6 | Portable/compact rigs |
21+
22+
<!-- GAP: Confirm which breadboard model is shipped with starter kits -->
23+
24+
## Bridging the Gap
25+
26+
Many standard breadboards have a **split in the power rails** halfway across the board. This can interrupt power flow in larger systems.
27+
28+
**The MICRORACK Solution:** Every MICRORACK module is designed to bridge the power rails. When you insert a module:
29+
30+
1. It draws power from the rails on its left side
31+
2. It passes power through to the rails on its right side
32+
3. Power flows continuously left-to-right, even across rail gaps
33+
34+
> **Tip:** If you're using a breadboard with a physical gap in the power rails, simply place a MICRORACK module over the gap to "bridge" the power to the other side.
35+
36+
## Module Placement
37+
38+
### Orientation Rules
39+
40+
- **Vertical Alignment:** Modules must be placed vertically to align power pins with the rails
41+
- **The Notch:** Always ensure the triangular notch is at the **bottom** of the module
42+
- **Power Pins:** Located at the bottom corners — they connect to the breadboard power rails
43+
44+
### Spacing
45+
46+
- Modules can be placed side-by-side with no gap
47+
- Leave gaps between modules for custom circuits or prototyping
48+
- The terminal strip area above modules is available for patching and experimentation
49+
50+
### Pin Layout
51+
52+
Per the MICRORACK Mechanical Specification:
53+
54+
| Position | Rail |
55+
|----------|------|
56+
| Bottom-left corners | GND, V12- |
57+
| Top-left corners | V12+, V5+ |
58+
| Bottom-right corners | GND, V12- |
59+
| Top-right corners | V12+, V5+ |
60+
61+
> **Safe Design:** If you accidentally insert a module backwards, it simply won't work — MICRORACK modules include reverse polarity protection and won't be damaged.

‎ecosystem/20-power/README.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Power Distribution
2+
3+
MICRORACK uses a standardized power distribution system to ensure all modules receive the correct voltages.
4+
5+
## The Power Rails
6+
7+
The system relies on four power rails distributed through the breadboard:
8+
9+
| Rail | Voltage | Color | Purpose |
10+
|------|---------|-------|---------|
11+
| **V12+** | +12V | Red | Positive supply for analog circuits |
12+
| **V5+** | +5V | — | Auxiliary supply for digital logic & LEDs |
13+
| **GND** | 0V | Black | Common ground reference |
14+
| **V12-** | -12V | Blue | Negative supply for bipolar signals |
15+
16+
> **Note:** The V5+ rail is intended for powering digital logic and LED indicators only. Do not use it as a voltage reference — modules should derive local regulated supplies internally.
17+
18+
## Current Limits
19+
20+
While breadboard rails are convenient, they have physical limits:
21+
22+
- **Maximum per rail:** 100 mA per individual power rail (per MICRORACK Specification)
23+
- **Voltage tolerance:** ±10% on all power rails
24+
- **Ripple:** Up to 200 mV peak-to-peak is acceptable
25+
26+
### Typical Module Consumption
27+
28+
| Module | Power Consumption |
29+
|--------|-------------------|
30+
| mod-vco | 732 mW |
31+
| mod-midi | 660 mW |
32+
| mod-in-63 | 348 mW |
33+
| mod-jacket | 24 mW |
34+
35+
<!-- GAP: Power consumption data needed for remaining modules -->
36+
37+
## Power Flow
38+
39+
Power flows from the **Power Module** through the breadboard rails. Each MICRORACK module acts as a "repeater," passing power from left to right through its power pins. This ensures continuous power distribution even across breadboard rail gaps.
40+
41+
## Hot-Swap Considerations
42+
43+
MICRORACK modules are designed to tolerate hot-swapping, but transient voltage spikes may occur when inserting modules with power on. For best practice, power off before adding or removing modules.
44+
45+
## Troubleshooting Power
46+
47+
- **Dim LEDs:** Too many modules on one rail, or underpowered supply.
48+
- **Noise/Whining:** Check that your Power Module is firmly seated and you're using a quality regulated DC adapter.
49+
- **No Power:** Verify power supply polarity and that the adapter meets voltage/current requirements.
50+
51+
<!-- GAP: Confirm actual power supply specs (voltage, current, polarity) shipped with kits -->
52+
53+
---
54+
55+
## Expanding Your System
56+
57+
One of the greatest strengths of MICRORACK is its scalability. You can start with a single breadboard and grow into a massive wall of sound.
58+
59+
### Connecting Multiple Breadboards
60+
61+
To expand your system, you can physically connect multiple breadboards using their built-in interlocking tabs.
62+
63+
#### Power Rail Jumpers
64+
65+
To share power between breadboards, connect each power rail:
66+
67+
| Rail | From Board A | To Board B |
68+
|------|--------------|------------|
69+
| V12+ | +12V rail | +12V rail |
70+
| V5+ | +5V rail | +5V rail |
71+
| GND | Ground rail | Ground rail |
72+
| V12- | -12V rail | -12V rail |
73+
74+
> **Wire Gauge:** Use short, thick jumper wires (22AWG or larger) to minimize voltage drop across long power runs.
75+
76+
### Distributed Power
77+
78+
For very large systems (3+ breadboards), we recommend using a dedicated **Power Module** for every two breadboards to ensure voltage stability and prevent current overload on the rails.
79+
80+
### Planning Your Expansion
81+
82+
| System Size | Breadboards | Power Modules | Notes |
83+
|-------------|-------------|---------------|-------|
84+
| Starter | 1 | 1 | Up to ~10 modules |
85+
| Medium | 2 | 1 | Chain power rails |
86+
| Large | 3-4 | 2 | One per 2 boards |
87+
| Studio | 5+ | 3+ | Consider star grounding |
88+
89+
<!-- GAP: Confirm recommended max modules per Power Module based on current draw -->

‎ecosystem/30-connections/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Connections & Patching
2+
3+
Patching is where the magic happens. MICRORACK uses a simple, color-coded system to make signal routing intuitive.
4+
5+
## The Pin Header Standard
6+
7+
Instead of bulky patch cables, MICRORACK uses standard **2.54mm male pin headers** for all inputs and outputs. This allows you to use:
8+
9+
| Cable Type | Description |
10+
|------------|-------------|
11+
| **Standard Jumper Wires** | Cheap and widely available from electronics suppliers |
12+
| **MICRORACK Patch Cables** | High-quality, flexible cables designed for the system |
13+
| **Breadboard Wire Kits** | Pre-cut lengths in various colors |
14+
15+
> **Tip:** For firmer connections (especially for frequently-used interfaces), double-row male pin headers can be used per the mechanical specification.
16+
17+
## Color Coding
18+
19+
MICRORACK follows a strict color-coding standard for pin headers:
20+
21+
| Color | Function | Description |
22+
|-------|----------|-------------|
23+
| **Blue** | **Input** | Audio or CV signals entering a module |
24+
| **Red** | **Output** | Audio or CV signals leaving a module |
25+
| **Black** | **Utility / GND** | Ground, clock sync, power extension, stylus voltage |
26+
27+
### I/O Placement Convention
28+
29+
Per the MICRORACK specification, inputs are typically placed on the **left side** and outputs on the **right side** of modules, at the top edge of the board.
30+
31+
## Patching Best Practices
32+
33+
### Basic Rules
34+
35+
- **Outputs to Inputs:** Always connect a Red pin (Output) to a Blue pin (Input)
36+
- **Never connect two Outputs:** Connecting two Red pins together can cause electrical contention
37+
38+
### Splitting Signals (Mults)
39+
40+
To send one output to multiple inputs:
41+
42+
1. Use "stackable" jumper wires that allow multiple connections
43+
2. Use a small breadboard area to create a passive mult
44+
3. Connect multiple wires to the same output pin (up to 2-3 destinations)
45+
46+
> **Note:** Per the electrical specification, each signal should have at least two output pins that duplicate the signal. This makes it easier to patch one signal to multiple destinations.
47+
48+
### Input Summing
49+
50+
Many MICRORACK modules sum multiple inputs together:
51+
52+
- Each input typically has 2+ pins that are summed internally
53+
- You can connect multiple sources to create complex modulation
54+
- This is useful for mixing CV signals (e.g., LFO + envelope → filter cutoff)
55+
56+
## Improve Cable Management
57+
58+
- Keep cables tidy to avoid accidentally pulling modules out
59+
- Use consistent color coding for different signal types (audio vs CV vs gate)
60+
- Write complex patches down to recall them later
61+
62+
The color coding makes it easy to trace signals: follow Red to Blue connections through your patch.
63+
64+
---
65+
66+
## Module Chaining
67+
68+
MICRORACK modules can be chained together in various ways to create complex signal paths.
69+
70+
### Signal Patching Across Breadboards
71+
72+
Signals can be patched between breadboards just as easily as within a single board. For long runs, we recommend:
73+
74+
- Keeping the boards physically close together
75+
- Using shielded cables for sensitive audio signals
76+
- Maintaining the color-coding convention (Red output → Blue input)
77+
78+
### Chaining Techniques
79+
80+
| Technique | Description | Use Case |
81+
|-----------|-------------|----------|
82+
| **Serial** | Output → Input → Output → Input | Effects chains, filters in series |
83+
| **Parallel** | One output to multiple inputs | Modulation distribution, audio splitting |
84+
| **Feedback** | Output looped back to earlier input | Self-oscillation, complex timbres |
85+
86+
### Clock & Gate Chaining
87+
88+
For sequenced and rhythmic patches:
89+
90+
- Use **Black (Utility)** pins for clock signals
91+
- Chain clock from master sequencer/clock module to all slaves
92+
- Gate signals follow the same Red → Blue convention as audio
93+
94+
> **Tip:** When building large patches across multiple breadboards, sketch your signal flow on paper first. This helps plan module placement and minimize cable lengths.

0 commit comments

Comments
 (0)