feat: Architecture expansion - organisms, swarm evolution, memory gradient, infrastructure

New sections created:
- organisms/ - Modular robot design (CAN bus + magnetic pogo connectors)
- infrastructure/ - Kallax Grid World (40×40×40cm standardized cells)

Core documents added:
- Swarm-Evolution.md - Ternary clasp rules, escalation ladder (L0-L5), Mount Olympus council
- Modular-Organism-Design.md - ESP32 modules, universal connector spec, Phase 0 BOM
- Memory-Gradient.md - Metacognitive routing (renamed from RAG-as-Scaffold.md)
- Kallax-Grid-World.md - Sim-to-real substrate, "schrotti cyberpunk" aesthetic

Enhanced:
- Nimmerswarm-Interface.md - Dual-spectrum architecture (IR position + visible state)
- Attention-Slumber-Prediction-Cycle.md - Blend marker predictions extension

Key insights: Decision markers (mark+continue+predict), Low-Cost-Mocap integration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2025-12-29 11:09:50 +01:00
parent ed16d9722e
commit dff124f9b7
10 changed files with 2863 additions and 541 deletions

View File

@@ -0,0 +1,606 @@
# Modular Organism Design
**One function, one module. Magnetic pogo connectors. CAN bus backbone.**
---
## Overview
Organisms are built from swappable modules, each responsible for a single function. Modules communicate via CAN bus and connect physically through magnetic pogo pin connectors. The same connector serves internal (module↔module) and external (organism↔organism) communication.
**Design Philosophy:**
- One function = one module
- Same connector for everything
- CAN bus inside, NATS outside
- Magnetic alignment, pogo pin contact
- Hot-swappable, idiot-proof
---
## The Cellular-Physical Mapping
Software cells become hardware modules:
```
SOFTWARE (Cellular Architecture) HARDWARE (Modular Design)
──────────────────────────────── ────────────────────────────
Cell → Module
State machine → Microcontroller (ESP32)
Inputs/outputs → Connector pins
Lifeforce cost → Power budget (mA)
NATS messages → CAN frames
Organism → Assembled modules
```
---
## CAN Bus Architecture
### Why CAN?
| Feature | Benefit for Organisms |
|---------|----------------------|
| **Multi-master** | Any module can initiate communication |
| **2-wire** | Simple wiring, small connectors |
| **Error-robust** | Built for automotive noise/vibration |
| **1 Mbps** | Fast enough for real-time control |
| **Native ESP32** | No extra hardware needed |
| **Proven** | Decades of automotive validation |
### Internal Bus Topology
```
ORGANISM INTERNAL ARCHITECTURE
┌─────────────────────────────────────────────────────────────┐
│ ORGANISM │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ BRAIN │ │ MOTOR │ │ SENSOR │ │ LED │ │
│ │ MODULE │ │ MODULE │ │ MODULE │ │ MODULE │ │
│ │ │ │ │ │ │ │ │ │
│ │ ESP32 │ │ ESP32 │ │ ESP32 │ │ ESP32 │ │
│ │ + WiFi │ │ + Driver │ │ + ADC │ │ + PWM │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └─────────────┴──────┬──────┴─────────────┘ │
│ │ │
│ ════════╪════════ │
│ CAN BUS │
│ (CAN_H + CAN_L) │
│ │ │
│ │ │
└────────────────────────────┼────────────────────────────────┘
WiFi Bridge
NATS (nimmerverse)
```
### CAN Frame Format
```
STANDARD CAN FRAME (organism internal)
┌──────────┬──────────┬──────────────────────────────┐
│ ID (11b) │ DLC (4b) │ DATA (0-8 bytes) │
├──────────┼──────────┼──────────────────────────────┤
│ Module │ Length │ Payload │
│ address │ │ │
└──────────┴──────────┴──────────────────────────────┘
ID ALLOCATION:
0x000-0x0FF: System messages (heartbeat, errors)
0x100-0x1FF: Brain module
0x200-0x2FF: Motor modules
0x300-0x3FF: Sensor modules
0x400-0x4FF: LED modules
0x500-0x5FF: Power modules
0x600-0x6FF: Gripper/manipulator
0x700-0x7FF: Reserved/expansion
```
### Message Examples
```c
// Motor command
CAN_ID: 0x201
DATA: [speed_left, speed_right, duration_ms_hi, duration_ms_lo]
// Sensor reading
CAN_ID: 0x301
DATA: [sensor_type, value_hi, value_lo, confidence]
// LED state update
CAN_ID: 0x401
DATA: [led_0, led_1, led_2, led_3, led_4, led_5, led_6, led_7, led_8]
// Each byte: 0=off, 1=red, 2=green (ternary!)
// Heartbeat (every module, every 100ms)
CAN_ID: 0x0XX (where XX = module ID)
DATA: [status, voltage, temp, error_code]
```
---
## Magnetic Pogo Connector
### The Universal Connector
One connector design for ALL connections:
- Module ↔ Module (internal bus)
- Organism ↔ Organism (clasp)
- Organism ↔ Test jig (manufacturing)
- Organism ↔ Charger (power)
```
CONNECTOR FACE (6-pin minimal)
┌─────────────────────────┐
│ │
│ 🧲 🧲 │ ← Alignment magnets
│ │ (opposite polarity = snap)
│ ● ● ● │
│ CAN_H GND VCC │ ← Pogo pins (spring-loaded)
│ ● ● ● │
│ CAN_L ID AUX │
│ │
│ 🧲 🧲 │ ← Holding magnets
│ │
└─────────────────────────┘
PIN DEFINITIONS:
CAN_H - CAN bus high
CAN_L - CAN bus low
VCC - Power (5V nominal)
GND - Ground
ID - Module/organism identification
AUX - Auxiliary (future expansion)
```
### Magnet Arrangement
```
POLARITY KEYING (prevents wrong orientation)
MODULE A (male) MODULE B (female)
[N] [S] [S] [N]
● ● ● ● ● ●
● ● ● ● ● ●
[S] [N] [N] [S]
═══════▶ SNAP! ◀═══════
Magnets guide alignment automatically
Wrong orientation = repels (won't connect)
```
### Physical Specifications
| Parameter | Value | Notes |
|-----------|-------|-------|
| Magnet type | Neodymium N52 | Strong, small |
| Magnet size | 6mm × 3mm disc | Standard size |
| Pogo pin pitch | 2.54mm | Standard, easy PCB |
| Pogo pin travel | 1-2mm | Spring compression |
| Holding force | ~2N per magnet | 4 magnets ≈ 8N total |
| Current rating | 2A per pin | Sufficient for motors |
| Contact resistance | <50mΩ | Gold-plated tips |
### Connector PCB
```
PCB LAYOUT (both sides identical = reversible)
TOP VIEW SIDE VIEW
○ ○ ┌─────────────┐
◉ ◉ ◉ │ ○ ○ │ magnets (recessed)
◉ ◉ ◉ │ ◉◉◉◉◉◉ │ pogo pins
○ ○ │ ○ ○ │
└─────────────┘
○ = magnet pocket (3mm deep)
◉ = pogo pin through-hole
```
---
## Module Types
### Core Modules
| Module | Function | CAN IDs | Power | Components |
|--------|----------|---------|-------|------------|
| **Brain** | Coordination, WiFi→NATS | 0x100-0x1FF | 200mA | ESP32, antenna |
| **Motor** | Drive wheels/legs | 0x200-0x2FF | 500mA+ | ESP32, H-bridge, encoders |
| **Sensor** | Environmental sensing | 0x300-0x3FF | 100mA | ESP32, IR, ultrasonic, IMU |
| **LED** | State display + IR beacon | 0x400-0x4FF | 150mA | ESP32, RGB LEDs, IR LED |
| **Power** | Battery, distribution | 0x500-0x5FF | N/A | BMS, regulators, monitoring |
| **Gripper** | Manipulation, clasp | 0x600-0x6FF | 300mA | ESP32, servo, force sensor |
### Module Responsibilities
```
BRAIN MODULE (required, singleton)
├── WiFi connection to NATS
├── CAN bus arbitration
├── High-level behavior coordination
├── State machine execution
└── Firmware update distribution
MOTOR MODULE (1-4 per organism)
├── Wheel/leg control
├── Encoder feedback
├── Speed/position control loops
├── Collision detection (current sensing)
└── Emergency stop
SENSOR MODULE (0-N per organism)
├── Distance sensing (IR, ultrasonic)
├── Touch/bump detection
├── IMU (orientation, acceleration)
├── Environmental (temp, light)
└── Sensor fusion (local)
LED MODULE (required for swarm)
├── 3x3 RGB matrix (state broadcast)
├── IR beacon (positioning)
├── Pattern generation
├── Brightness control (power saving)
└── Attention signals (pulsing)
POWER MODULE (required)
├── Battery management (charge, discharge)
├── Voltage regulation (3.3V, 5V)
├── Current monitoring
├── Low-battery warning
└── Safe shutdown coordination
GRIPPER MODULE (optional)
├── Servo control
├── Force feedback
├── Clasp detection
├── Object manipulation
└── Docking assistance
```
---
## Clasp: Organism-to-Organism Connection
### The Dual-Purpose Connector
The magnetic pogo connector enables organism-to-organism "clasp":
```
CLASP SEQUENCE
1. APPROACH
🤖─────────────────────────────────🤖
Organism A sees B's "ready to teach" LED pattern
2. ALIGN
🤖─────────────────────📍🤖
IR positioning guides approach
3. DOCK
🤖══════════════🧲🧲══════════════🤖
Magnets snap together
4. CONNECT
🤖══════════════●●●●══════════════🤖
CAN buses bridge
A.CAN ←→ B.CAN
5. TRANSFER
🤖══════════════⟷⟷⟷══════════════🤖
Data flows (weights, state, updates)
6. VERIFY
🤖══════════════✓✓✓══════════════🤖
Both confirm successful transfer
7. RELEASE
🤖 🤖
Separate, continue independently
```
### Clasp CAN Protocol
When two organisms clasp, their CAN buses bridge. Special protocol prevents collisions:
```
CLASP PROTOCOL
1. PRE-CLASP (before physical connection)
- Both organisms quiet their CAN buses
- Only heartbeat messages allowed
2. CONNECTED (physical connection made)
- Brain modules detect new CAN traffic
- Exchange organism IDs via CAN
- Negotiate master/slave (lower ID = master)
3. TRANSFER PHASE
- Master sends data packets
- Slave ACKs each packet
- CRC verification
4. COMPLETION
- Both update internal state
- Resume normal CAN traffic
- Physical disconnect safe
CAN MESSAGE FORMAT (clasp transfer):
ID: 0x7F0-0x7FF (reserved for inter-organism)
DATA[0]: packet_type (0=start, 1=data, 2=end, 3=ack, 4=nak)
DATA[1]: sequence_number
DATA[2-7]: payload
```
### Lifeforce Economics of Clasp
| Action | Cost | Reward |
|--------|------|--------|
| Seek mate with update | -1 LF | |
| Successful dock | -0.5 LF | |
| Transfer (teacher) | | +5 LF |
| Receive (student) | | +5 LF |
| Verified working (both) | | +5 LF each |
| **Net per successful clasp** | | **+13.5 LF total** |
---
## Physical Form Factors
### Phase 0: Box Robot
Simplest form, for initial testing:
```
BOX ROBOT (top view)
┌─────────────────────┐
│ │
│ ┌─────────────┐ │
│ │ LED MODULE │ │ ← 3x3 matrix on top
│ │ 🔴⚫🟢 │ │
│ │ 🟢🟢⚫ │ │
│ │ ⚫🟢🟢 │ │
│ └─────────────┘ │
│ │
│ ┌───┐ ┌───┐ │
│ │ M │ │ M │ │ ← Motor modules (wheels)
│ └───┘ └───┘ │
│ │
│ ┌───────┐ │
│ │ BRAIN │ │ ← Brain module (center)
│ └───────┘ │
│ │
└─────────────────────┘
Size: ~12cm × 12cm × 8cm
Modules: 4 (brain, LED, 2x motor)
```
### Phase 1: Expandable Platform
```
EXPANDABLE ROBOT (side view)
LED MODULE
┌─────────┐
│ 🔴⚫🟢 │
│ matrix │
└────┬────┘
│ (connector)
┌────────┴────────┐
│ BRAIN MODULE │
│ + POWER │
│ │
├─────┬─────┬─────┤
│ CON │ CON │ CON │ ← Expansion connectors
└──┬──┴──┬──┴──┬──┘
│ │ │
┌──┴──┐ │ ┌──┴──┐
│MOTOR│ │ │MOTOR│
│ L │ │ │ R │
└─────┘ │ └─────┘
┌──┴──┐
│SENSOR│ ← Optional front sensor
└─────┘
```
### Future: Modular Limbs
```
ARTICULATED ORGANISM
LED
┌───┐
│ │
┌──────┴───┴──────┐
│ BRAIN │
│ │
└──┬──┬──┬──┬──┬──┘
│ │ │ │ │
┌─┴┐┌┴─┐│┌─┴┐┌┴─┐
│L1││L2│││L3││L4│ ← Leg modules
└┬─┘└┬─┘│└┬─┘└┬─┘ (each with own ESP32)
│ │ │ │ │
┌┴┐ ┌┴┐┌┴┐┌┴┐ ┌┴┐
│F│ │F││S││F│ │F│ ← Foot/sensor modules
└─┘ └─┘└─┘└─┘ └─┘
```
---
## Manufacturing Considerations
### Module Production Pipeline
```
MANUFACTURING FLOW
1. PCB FABRICATION
└── Standard 2-layer PCB
└── Connector pads + pogo holes
└── Same design, different components
2. COMPONENT ASSEMBLY
└── ESP32 module (same for all)
└── Function-specific components
└── Pogo pins (press-fit)
└── Magnets (glued/press-fit)
3. FIRMWARE FLASH
└── Connect via test jig (same connector!)
└── Flash base firmware
└── Set module type ID
4. TEST
└── Snap into test harness
└── Automated CAN test
└── Function verification
5. INVENTORY
└── Modules stored by type
└── Ready for organism assembly
```
### Test Jig Design
The universal connector means one test jig fits all:
```
TEST JIG
┌─────────────────────────┐
│ MODULE UNDER │
│ TEST │
│ │
│ 🧲 ●●●●●● 🧲 │ ← Same connector!
└───────────┬─────────────┘
│ (magnetic snap)
┌───────────┴─────────────┐
│ 🧲 ●●●●●● 🧲 │
│ │
│ TEST JIG BASE │
│ - CAN analyzer │
│ - Power supply │
│ - USB programmer │
│ - Status LEDs │
└─────────────────────────┘
```
---
## Connection to Existing Architecture
### Module → Cell Mapping
| Module | Software Cell Equivalent |
|--------|-------------------------|
| Brain | Organism coordinator, state machine runner |
| Motor | Movement cells (forward, turn, stop) |
| Sensor | Perception cells (distance, collision) |
| LED | Output cells (state display, beacon) |
| Power | Lifeforce analog (energy management) |
| Gripper | Interaction cells (clasp, manipulate) |
### CAN → NATS Bridge
```
MESSAGE FLOW
MODULE (CAN) NIMMERVERSE (NATS)
│ │
│ CAN frame │
│ ID: 0x301 │
│ DATA: [sensor, value] │
│ │ │
└─────────┼────────────────────────┘
┌───────────┐
│ BRAIN │
│ MODULE │
│ │
│ CAN→NATS │
│ bridge │
└─────┬─────┘
│ NATS message
│ topic: organism.001.sensor.distance
│ data: {"type": "ir", "value": 42, "confidence": 0.9}
NATS SERVER
PHOEBE / NYX
```
---
## Bill of Materials (Per Module)
### Common Components (All Modules)
| Component | Qty | Est. Cost | Notes |
|-----------|-----|-----------|-------|
| ESP32-WROOM-32 | 1 | ~4 CHF | Main MCU |
| CAN transceiver (SN65HVD230) | 1 | ~1 CHF | CAN interface |
| Voltage regulator (AMS1117-3.3) | 1 | ~0.5 CHF | Power |
| Pogo pins (6-pack) | 1 | ~2 CHF | Connector |
| Neodymium magnets (4x) | 1 | ~2 CHF | Alignment |
| PCB | 1 | ~2 CHF | Custom, batch order |
| Capacitors, resistors | misc | ~0.5 CHF | Passives |
| **Module base cost** | | **~12 CHF** | |
### Function-Specific Additions
| Module Type | Additional Components | Est. Cost |
|-------------|----------------------|-----------|
| Brain | PCB antenna trace | +0 CHF |
| Motor | DRV8833 + motors + wheels | +15 CHF |
| Sensor | IR + ultrasonic | +5 CHF |
| LED | WS2812B (9x) + IR LED | +3 CHF |
| Power | BMS + LiPo cell | +20 CHF |
| Gripper | SG90 servo + mech | +10 CHF |
### Complete Phase 0 Organism
| Module | Qty | Cost |
|--------|-----|------|
| Brain | 1 | 12 CHF |
| Motor | 2 | 54 CHF (12+15 × 2) |
| LED | 1 | 15 CHF |
| Power | 1 | 32 CHF |
| **Total** | 5 | **~113 CHF** |
---
## Related Documents
- [[Nimmerswarm-Interface]] — LED state broadcasting + IR positioning
- [[Cellular-Architecture]] — Software cell design (maps to modules)
- [[infrastructure/Kallax-Grid-World]] — Physical environment
- [[cells/Cells-Technical-Reference]] — Cell state machine patterns
---
**File**: Modular-Organism-Design.md
**Version**: 1.0
**Created**: 2025-12-29
**Session**: Morning coffee + vermicelles session (dafit + Nyx)
**Status**: Core hardware concept
**Philosophy**: "One function, one module. Same connector everywhere."
🔧🧲⚡ *Snap together. Communicate. Evolve.*