# SILCARP Open CAN Bus Architecture & RealDash Telemetry
**Document ID:** `SILCARP-SW-CAN-001`  
**License:** CERN-OHL-S v2 / CC BY-SA 4.0  
**Target Bus:** ISO 11898-2 High-Speed CAN, 500 kbps, 11-bit standard IDs  
**Artifacts:** [`can/silcarp_can_v1.dbc`](file:///opt/eidos/silcarp/can/silcarp_can_v1.dbc) · [`can/realdash_silcarp.xml`](file:///opt/eidos/silcarp/can/realdash_silcarp.xml)  

---

## 1. Network Topology & Physical Layer

The SILCARP powertrain and instrumentation run on a single, clean, robust **500 kbps CAN 2.0B bus**. 

```
   [ 120 Ohm Terminator ]                                      [ 120 Ohm Terminator ]
            |                                                           |
   +--------+--------+      +---------------+      +----------------+   |
   | ZombieVerter    |======| LilyGO BMS    |======| Skeleton Cap   |===+
   | VCU             |  CAN | CAN Bridge    |  CAN | Telemetry      |   |
   +--------+--------+  BUS +---------------+  BUS +----------------+   |
            ||                                                          |
   +--------+--------+                                 +----------------+---+
   | RealDash USB    |=================================| Trampa VESC 100/250 |
   | CANable 2.0     |                                 | FOC Inverter       |
   +-----------------+                                 +--------------------+
```

### Physical Specifications
- **Baud Rate:** 500,000 bps (500 kbps).
- **Wiring:** Twisted shielded pair ($0.5\text{ mm}^2$ / AWG 20), characteristic impedance $120\,\Omega \pm 10\%$.
- **Termination:** Two $120\,\Omega$ $0.25\text{W}$ metal film resistors:
  1. Internal jumper on the **ZombieVerter VCU** (Front termination node).
  2. Internal resistor on the **Trampa VESC 100/250** (Rear termination node).
- **Connector Standard:** Deutsch DT 3-pin connectors (`CAN_H` = Pin 1, `CAN_L` = Pin 2, `SHIELD_GND` = Pin 3).

---

## 2. CAN Message Frame Matrix

| CAN ID (Hex) | CAN ID (Dec) | Message Name | Transmitter | Repetition Rate | Primary Contents |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `0x100` | 256 | `VCU_Status` | VCU | 50 Hz (20 ms) | Drive State (PRND), Throttle %, Brake bar, Door safety lock |
| `0x101` | 257 | `VCU_TorqueCommand` | VCU | 100 Hz (10 ms) | Target Torque (Nm), Max RPM, Regen limit, Inverter Enable |
| `0x200` | 512 | `VESC_Status1` | VESC | 50 Hz (20 ms) | Motor ERPM, Phase Current (A), Duty Cycle |
| `0x203` | 515 | `VESC_Status4` | VESC | 20 Hz (50 ms) | MOSFET Temp (°C), Motor Temp (°C), DC Input Current |
| `0x204` | 516 | `VESC_Status5` | VESC | 20 Hz (50 ms) | Odometer pulses, Bus Voltage (V), Fault Code |
| `0x300` | 768 | `BMS_PackStatus` | BMS Bridge | 10 Hz (100 ms) | Pack Voltage (V), Current (A), SoC %, SoH %, Fault flags |
| `0x301` | 769 | `BMS_CellLimits` | BMS Bridge | 5 Hz (200 ms) | Max Cell (mV), Min Cell (mV), Max/Min Temp (°C) |
| `0x400` | 1024 | `SKELETON_Status` | Ultracap | 20 Hz (50 ms) | Ultracap Voltage (V), Current (A), SoC %, Wh stored |
| `0x500` | 1280 | `CLUSTER_DisplayFeed`| VCU | 20 Hz (50 ms) | Speed (km/h), Power (kW), Range (km), 12V Aux V, Warning lamps |

---

## 3. RealDash Instrument Cluster Configuration

RealDash runs seamlessly on any Android 8.0+ tablet, repurposed smartphone, or Raspberry Pi 4/5 via HDMI.

### 3.1 Hardware Adapter Options
1. **CANable 2.0 (Recommended):** ~$25 open-hardware USB-to-CAN adapter running `candleLight` firmware. Plugs directly into the tablet USB-C port via OTG.
2. **ESP32 Wi-Fi / Bluetooth Gateway:** Broadcasts CAN frames over local UDP socket directly to RealDash.

### 3.2 Loading the SILCARP Profile into RealDash
1. Copy [`can/realdash_silcarp.xml`](file:///opt/eidos/silcarp/can/realdash_silcarp.xml) to the device storage.
2. In RealDash: `Settings` $\to$ `Connections` $\to$ `Add Connection` $\to$ `CAN / LIN` $\to$ `Generic / Custom CAN XML`.
3. Select `CANable (candleLight)` as hardware, set baud rate to `500,000`.
4. Load `realdash_silcarp.xml`.
5. Instant digital gauges:
   - Big center numeric speedometer (km/h) + power needle (kW).
   - Battery SoC gauge (%) + high-voltage bus reading.
   - Motor and Inverter temperature dials with redline warnings at 110°C / 75°C.
   - Status indicators: Door Ajar, Brake Fluid Low, Turtle Mode, Master Hazard.

---

## 4. Software Emulation & Virtual Testing (`vcan0`)

You can test the entire SILCARP CAN telemetry stack on Linux without touching hardware using `vcan0` (virtual CAN):

```bash
# Setup virtual CAN interface on Linux
sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0

# Listen to the bus with can-utils
candump vcan0

# Test transmission using the python mock script below
python3 scripts/mock_can_stream.py
```

### Python Mock Telemetry Generator (`scripts/mock_can_stream.py`)
A lightweight script sending realistic vehicle telemetry frames (speed ramps, battery drain, regenerative braking pulses) is maintained in `scripts/mock_can_stream.py`.
