Switchberry

Raspberry Pi Compute Module based, Managed 1G Ethernet Switch with PTP Support

Switchberry is a Raspberry Pi CM4–controlled Ethernet switching + timing platform built around a Microchip KSZ9567 and a Renesas 8A34004 ClockMatrix DPLL. It’s designed for PTP / SyncE / timing lab workflows while staying flexible enough to run as a compact managed switch/router with precise timing I/O.

<img width="999" height="657" alt="529070621-42df475b-2fe9-462f-92c0-70f97fde4533" src="https://github.com/user-attachments/assets/a4ab64b3-9412-491a-b70a-377372f48dde" />

---

Order

Switchberry is available for purchase on Tindie:

👉 Buy Switchberry on Shopify

👉 Buy Switchberry on Tindie

---

Table of Contents

• Order

• Quick Start

  • Out-of-the-Box Behavior
  • Accessing the Raspberry Pi CM4
  • Customize & Monitor

• Key Features

• Hardware Overview

• Timing & Sync Capabilities

• Typical Use Cases

• Notes

• License

Software & Tools

| Guide | Description | | :--- | :--- | | Software Quick Start | Timing/PTP setup, config wizard, detailed from-scratch install | | Switch CLI | KSZ9567 port status, counters, and init via SPI | | Daemons & Services | Systemd service chain, boot sequence, Makefile control | | ClockMatrix Utilities | dplltool, config.py wizard, apply_timing.py, DPLL monitor | | Enclosure | Enclosure design files | | Partial Schematic | Board schematic reference |

---

Quick Start

Out-of-the-Box Behavior

With no configuration, Switchberry works as a plug-and-play Layer 2 unmanaged Ethernet switch with PTP hardware transparent clock enabled:

• All 5 front-panel RJ45 ports are on the same switch plane and forward traffic at line rate — just plug in Ethernet cables
• The CM4 is connected to the switch via an internal port that is always up, so any front-panel port can be used to reach the CM4 over the network
• PTP transparent clock is active by default — PTP packets are forwarded with hardware residence-time correction, no setup needed
• No VLANs, IP configuration, or switch management required to start using it as a switch

Accessing the Raspberry Pi CM4

Default login: pi / password

The CM4 is available through three interfaces:

| Method | Connector | Details | | :--- | :--- | :--- | | Ethernet (DHCP) | Any front-panel RJ45 port | CM4 obtains an IP via DHCP. SSH in with ssh pi@<ip-address> — use find_switchberry.py or check your router to find the IP. | | Serial console | Micro-USB (side panel) | Appears as a USB UART. Connect with PuTTY or Tera Term (Windows) or tio (Linux) at 115200 baud. On a fresh SD card image, add enable_uart=1 to config.txt first. | | Display + keyboard | Micro-HDMI + USB-A | Connect a monitor via micro-HDMI and a keyboard via USB-A for direct console/desktop access. |

Tip: Use find_switchberry.py from your PC to automatically discover Switchberry devices on your LAN:

python3 find_switchberry.py

Customize & Monitor

Clone the repo and make scripts executable:

cd ~/
git clone https://github.com/Time-Appliances-Project/Switchberry
cd Switchberry/Software
git config core.fileMode false
chmod +x sb-*.sh install_all.sh

Then configure and apply:

./sb-config.sh          # Interactive wizard — configure PTP role, timing sources, SMA routing
sudo ./sb-reinstall.sh  # Reinstall & restart (runs in background — safe over SSH)
./sb-status.sh          # Check DPLL lock state, PTP sync, and service health from the CLI

A web status dashboard also runs on port 8080 — open http://<switchberry-ip>:8080 in any browser on the same network to see live system status.

For the full guide, see the Software Quick Start Guide.

---

Key Features

• 5× front-panel RJ45 ports driven by a KSZ9567 switch
• Raspberry Pi CM4 controller managing the switch over SPI
• Renesas 8A34004 ClockMatrix DPLL as the central timing hub
• Local TCXO reference for the ClockMatrix (drives derived clocks)
• OCP M.2 GNSS slot (GPS/GNSS timing card support)
• PCIe M.2 2230 slot (Wi-Fi 6E / Wi-Fi 7 modules)
• 4× rear SMA ports with muxing for multiple input/output routing options
• SyncE recovery from the switch into the DPLL (endpoint / boundary clock roles)
• PTP modes: hardware transparent clock (typical) or Linux DSA for software-defined behavior
• CM4 ↔ DPLL PPS routing supports both PTP Grandmaster and PTP client workflows

---

Hardware Overview

Ethernet Switching (KSZ9567)

• Switch: Microchip KSZ9567
• Front panel: 5× RJ45 ports
• SFP: Present on KSZ9567 but unused in this design (not used because it doesn’t support PTP)

Controller / Host (CM4)

• Compute: Raspberry Pi CM4
• Switch management: CM4 controls the KSZ9567 over SPI
• Uplink path to the switch:
  • CM4 Ethernet MAC → KSZ9031 PHY → KSZ9567 (connected as one switch port)

Timing Core (ClockMatrix)

• DPLL: Renesas 8A34004 ClockMatrix
  • Central point for all timing signals (distribution, recovery, synthesis)
• Reference oscillator: Local TCXO
  • Feeds the ClockMatrix and serves as the base reference for derived clocks

Expansion

• GNSS: OCP M.2 GNSS slot for GPS/GNSS cards
• Wi-Fi: PCIe M.2 2230 slot for Wi-Fi modules (Wi-Fi 6E / Wi-Fi 7 capable cards)

Rear I/O (SMA)

• 4× SMA ports on the back panel
• Each SMA has muxing, allowing configurable input/output options depending on timing mode and setup

---

Timing & Sync Capabilities

SyncE

• Switchberry can recover the SyncE clock from the KSZ9567 and feed it into the ClockMatrix DPLL.
• Enables operation as a SyncE endpoint or SyncE boundary clock (and equivalent roles depending on configuration).

PTP (IEEE 1588)

The KSZ9567 can be operated in multiple modes depending on the use case:

• Transparent Clock (typical):
  • KSZ9567 runs in transparent clock mode with hardware forwarding.
• Linux DSA (optional):
  • Run the switch under the DSA kernel architecture to behave more like a software router
  • Useful for experimentation with boundary clock / software-defined forwarding behavior

PPS Routing (CM4 ↔ DPLL)

• The PPS associated with the CM4 Ethernet port routes to the DPLL as both input and output.
• Supports:
  • PTP Grandmaster operation
    • CM4 disciplines to a PPS input from the DPLL, derived from GNSS or an external 1PPS source.
  • PTP client operation
    • CM4 recovers timing via PTP over the Ethernet switch and provides 1PPS to the DPLL.

---

Typical Use Cases

• PTP networking
  • Transparent clock, boundary clock experimentation, lab deployments
• SyncE networking
  • Endpoint / boundary clock setups using recovered SyncE into the DPLL
• PTP Grandmaster
  • GNSS-referenced or externally referenced timing with PPS discipline
• PTP client
  • Recover PPS via PTP and feed the DPLL
• TSN experimentation
  • With additional scripting/development
• DPLL development
  • Clocking experiments, holdover testing, input qualification, output synthesis
• Arbitrary frequency generator
  • Using ClockMatrix outputs via configurable SMA routing
• PPS ↔ frequency conversion
  • Convert/derive timing signals via the DPLL and output routing
• Wi-Fi bridge
  • Wi-Fi 6E / Wi-Fi 7 connectivity via M.2 2230 (e.g., bridging/edge deployments)

---

Notes

• The KSZ9567 SFP port is unused in this design because it doesn’t support PTP for the intended timing workflows.
• SMA functions are mode-dependent and determined by the mux configuration and ClockMatrix setup.

---

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).

You are free to:

Share — copy and redistribute the material in any medium or format Adapt — remix, transform, and build upon the material Under the following terms:

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. NonCommercial — You may not use the material for commercial purposes. For full details, see: https://creativecommons.org/licenses/by-nc/4.0/

As the project creator, I reserve the right to use this material commercially or under any other terms.