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.

---

Table of Contents

• 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

Once logged in, the software lives in ~/Switchberry/Software/:

./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.

---

Order

Coming soon!!!

---

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.