# openbmc/openbmc-tools architecture

> Architecture diagram of the GitHub repository openbmc/openbmc-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbmc/openbmc-tools
- Repository: https://github.com/openbmc/openbmc-tools

## Overview

This repository is not one integrated application; it is a toolbox of mostly independent OpenBMC utilities and one-off scripts. The main architectural boundary is per-directory: each top-level folder is its own small tool, with its own runtime, packaging, and dependencies.

The repository is organized around a few recurring interaction surfaces in OpenBMC: D-Bus, journald/log files, IPMI, sensor/I2C hardware, and boot/reboot workflows. Most tools are thin adapters that either query one of those surfaces, transform captured data, or automate a repeated operator task.

A large subset is low-level hardware and sensor tooling. Examples include `adcapp`, `pwmtachtool`, `bi2cp`, `i2c/tree.py`, and `sensor_yaml_config`. These tools map directly onto device interfaces such as ADCs, PWM/tachometer control, I2C topology, and sensor configuration files. Their data flow is typically “read hardware or config -> report/transform values” rather than service-to-service orchestration.

Another important subsystem is D-Bus capture and visualization. `dbus-pcap` captures bus traffic into packet-capture form, while `dbus-vis` and `dbusView` consume those captures and render timelines/interactive views in a browser/JS stack. This forms a clear offline analysis pipeline: live bus activity -> capture file -> visualization.

Logging and diagnostics are handled by small, file-oriented analyzers such as `pretty-journal`, `check_journal`, and `nginx-log-analysis`. These tools read existing logs, normalize or summarize them, and emit human-readable diagnostics. They are not daemons; they are operator-facing post-processing tools.

Boot and reboot automation is another distinct cluster. `reboot`, `reboot-ping-pong`, `netboot`, `prepare-emmc-qemu`, and `pldm/pdrdump.sh` all support firmware bring-up, reboot validation, or test-environment preparation. The typical flow here is “drive a board/QEMU/system action -> observe boot outcome or generated state.”

There is a command-line management layer for interacting with OpenBMC itself. `openbmctool` is the main example; it is a Python CLI with a `policyTable.json` that suggests command/permission mapping or request shaping. `witherspoon-debug`, `altitude`, `overlay`, and `bbdbg` are similarly specialized utilities for board-specific or platform-specific debugging.

Several directories are meta-tooling for repository and process automation rather than OpenBMC runtime interaction. `tof-voters` analyzes Gerrit reviews/commits against configured patterns, `cla-signers` manages CLA-related signer data, and `openbmc-autobump` automates version or dependency bumps. These tools connect to external developer workflow systems such as Gerrit and operate on repository metadata rather than device state.

There is also a set of format/transform helpers: `autojson`, `format-yaml`, `expectedJsonChecker`, and `ddconvnotrunc`. These are small conversion/validation utilities that sit between raw data and the structured formats used elsewhere in the repo.

Implementation technologies are intentionally mixed and lightweight. Python dominates most of the scripts, with shell wrappers for automation, C/C++ for performance- or device-facing utilities, and JavaScript/HTML/CSS for the D-Bus visualization frontend. Build systems are per-tool and independent: autotools, Meson, Makefiles, and simple executable scripts coexist without a shared monorepo build.

Operationally, the repo has very weak coupling by design. There is no shared application server, no central runtime, and no common data store. The architectural picture is a collection of command-line entry points and small UI tools that each ingest one kind of OpenBMC artifact, perform a narrow transformation, and write to stdout, files, or a browser UI.

For an architecture diagram, the most accurate abstraction is: “operator/dev tooling repository” at the center, with separate spokes to OpenBMC device interfaces, log/capture files, boot environments, and Gerrit/CLA workflow services. Each folder is an independent leaf rather than a module in a single system.

Main entry points: [`dbus-pcap`](https://github.com/openbmc/openbmc-tools/tree/master/dbus-pcap) (dbus-pcap), [`dbus-vis`](https://github.com/openbmc/openbmc-tools/tree/master/dbus-vis) (dbus-vis), [`openbmctool/openbmctool.py`](https://github.com/openbmc/openbmc-tools/blob/master/openbmctool/openbmctool.py) (openbmctool), [`reboot/reboot.sh`](https://github.com/openbmc/openbmc-tools/blob/master/reboot/reboot.sh) (reboot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["OpenBMC tools"]
  node_repo_root["Toolbox<br/>repo collection"]
end

subgraph group_hardware["Hardware tools"]
  node_adcapp["ADC app<br/>C tool"]
  node_pwmtachtool["PWM/tach<br/>C tool"]
  node_bi2cp["bi2cp<br/>I2C tool"]
  node_i2c_tree["I2C tree<br/>Python script<br/>[tree.py]"]
  node_sensor_yaml_config["Sensor config<br/>Python tool"]
end

subgraph group_dbus["D-Bus analysis"]
  node_dbus_pcap["dbus-pcap<br/>capture tool"]
  node_dbus_vis["dbus-vis<br/>JS frontend"]
  node_dbus_view["dbusView<br/>Python viewer<br/>[dbusView.py]"]
end

subgraph group_logs["Logs and diagnostics"]
  node_pretty_journal["pretty-journal<br/>log formatter<br/>[pretty-journal.py]"]
  node_check_journal["check_journal<br/>log checker"]
  node_nginx_analysis["nginx logs<br/>analysis script"]
end

subgraph group_boot["Boot workflows"]
  node_reboot["reboot<br/>shell workflow<br/>[reboot.sh]"]
  node_reboot_pp["ping-pong<br/>reboot test"]
  node_netboot["netboot<br/>boot helper"]
  node_prepare_emmc["eMMC prep<br/>QEMU helper"]
  node_pldm_pdrdump["pdrdump<br/>PLDM script<br/>[pdrdump.sh]"]
end

subgraph group_cli["BMC CLI and debug"]
  node_openbmctool["openbmctool<br/>Python CLI<br/>[openbmctool.py]"]
  node_witherspoon_debug["witherspoon-debug<br/>board debug"]
  node_overlay["overlay<br/>debug helper"]
end

subgraph group_meta["Workflow automation"]
  node_tof_voters["tof-voters<br/>workflow tool"]
  node_cla_signers["cla-signers<br/>workflow script<br/>[update-cla.sh]"]
  node_autobump["autobump<br/>release automation"]
end

subgraph group_format["Transform helpers"]
  node_autojson["autojson<br/>converter<br/>[autojson.py]"]
  node_format_yaml["format-yaml<br/>formatter<br/>[format-yaml.py]"]
  node_expected_checker["JSON checker<br/>validator"]
  node_ddconvnotrunc["ddconvnotrunc<br/>conversion helper"]
end

node_repo_root -->|"contains"| node_adcapp
node_repo_root -->|"contains"| node_pwmtachtool
node_repo_root -->|"contains"| node_bi2cp
node_repo_root -->|"contains"| node_i2c_tree
node_repo_root -->|"contains"| node_sensor_yaml_config
node_repo_root -->|"contains"| node_dbus_pcap
node_repo_root -->|"contains"| node_dbus_vis
node_repo_root -->|"contains"| node_dbus_view
node_repo_root -->|"contains"| node_pretty_journal
node_repo_root -->|"contains"| node_check_journal
node_repo_root -->|"contains"| node_nginx_analysis
node_repo_root -->|"contains"| node_reboot
node_repo_root -->|"contains"| node_reboot_pp
node_repo_root -->|"contains"| node_netboot
node_repo_root -->|"contains"| node_prepare_emmc
node_repo_root -->|"contains"| node_openbmctool
node_repo_root -->|"contains"| node_witherspoon_debug
node_repo_root -->|"contains"| node_overlay
node_repo_root -->|"contains"| node_tof_voters
node_repo_root -->|"contains"| node_cla_signers
node_repo_root -->|"contains"| node_autobump
node_repo_root -->|"contains"| node_autojson
node_repo_root -->|"contains"| node_format_yaml
node_repo_root -->|"contains"| node_expected_checker
node_repo_root -->|"contains"| node_ddconvnotrunc
node_repo_root -->|"contains"| node_pldm_pdrdump
node_dbus_pcap -->|"capture -> view"| node_dbus_vis
node_dbus_pcap -->|"capture -> view"| node_dbus_view
node_dbus_vis -->|"loads"| node_dbus_pcap
node_dbus_vis -->|"parses"| node_ddconvnotrunc
node_pretty_journal -->|"normalizes"| node_check_journal
node_reboot -->|"drives"| node_reboot_pp
node_reboot -->|"boot flow"| node_netboot
node_prepare_emmc -->|"prepares"| node_netboot
node_openbmctool -.->|"talks via"| node_dbus_pcap
node_openbmctool -.->|"complements"| node_witherspoon_debug
node_tof_voters -.->|"workflow"| node_cla_signers
node_tof_voters -.->|"automation"| node_autobump
node_autojson -->|"transforms"| node_format_yaml
node_autojson -->|"validates"| node_expected_checker
node_adcapp -.->|"configures"| node_sensor_yaml_config
node_pwmtachtool -.->|"hardware access"| node_bi2cp
node_i2c_tree -.->|"maps"| node_bi2cp
node_pldm_pdrdump -.->|"diagnostics"| node_openbmctool

click node_adcapp "https://github.com/openbmc/openbmc-tools/tree/master/adcapp"
click node_pwmtachtool "https://github.com/openbmc/openbmc-tools/tree/master/pwmtachtool"
click node_bi2cp "https://github.com/openbmc/openbmc-tools/tree/master/bi2cp"
click node_i2c_tree "https://github.com/openbmc/openbmc-tools/blob/master/i2c/tree.py"
click node_sensor_yaml_config "https://github.com/openbmc/openbmc-tools/blob/master/sensor_yaml_config/sensor_yaml_config.py"
click node_dbus_pcap "https://github.com/openbmc/openbmc-tools/tree/master/dbus-pcap"
click node_dbus_vis "https://github.com/openbmc/openbmc-tools/tree/master/dbus-vis"
click node_dbus_view "https://github.com/openbmc/openbmc-tools/blob/master/dbusView/dbusView.py"
click node_pretty_journal "https://github.com/openbmc/openbmc-tools/blob/master/pretty-journal/pretty-journal.py"
click node_check_journal "https://github.com/openbmc/openbmc-tools/tree/master/check_journal/check_journal"
click node_nginx_analysis "https://github.com/openbmc/openbmc-tools/tree/master/nginx-log-analysis/analyze-nginx-log"
click node_reboot "https://github.com/openbmc/openbmc-tools/blob/master/reboot/reboot.sh"
click node_reboot_pp "https://github.com/openbmc/openbmc-tools/tree/master/reboot-ping-pong/rpp"
click node_netboot "https://github.com/openbmc/openbmc-tools/tree/master/netboot/netboot"
click node_prepare_emmc "https://github.com/openbmc/openbmc-tools/tree/master/prepare-emmc-qemu/prepare-emmc-qemu"
click node_openbmctool "https://github.com/openbmc/openbmc-tools/blob/master/openbmctool/openbmctool.py"
click node_witherspoon_debug "https://github.com/openbmc/openbmc-tools/tree/master/witherspoon-debug/debug"
click node_overlay "https://github.com/openbmc/openbmc-tools/tree/master/overlay/overlay"
click node_tof_voters "https://github.com/openbmc/openbmc-tools/tree/master/tof-voters/libvoters"
click node_cla_signers "https://github.com/openbmc/openbmc-tools/blob/master/cla-signers/update-cla.sh"
click node_autobump "https://github.com/openbmc/openbmc-tools/blob/master/openbmc-autobump/openbmc-autobump.py"
click node_autojson "https://github.com/openbmc/openbmc-tools/blob/master/autojson/autojson.py"
click node_format_yaml "https://github.com/openbmc/openbmc-tools/blob/master/format-yaml/format-yaml.py"
click node_expected_checker "https://github.com/openbmc/openbmc-tools/tree/master/expectedJsonChecker"
click node_ddconvnotrunc "https://github.com/openbmc/openbmc-tools/tree/master/ddconvnotrunc/ddconvnotrunc"
click node_pldm_pdrdump "https://github.com/openbmc/openbmc-tools/blob/master/pldm/pdrdump.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo_root,node_tof_voters,node_cla_signers,node_autobump toneBlue
class node_adcapp,node_pwmtachtool,node_bi2cp,node_i2c_tree,node_sensor_yaml_config,node_autojson,node_format_yaml,node_expected_checker,node_ddconvnotrunc toneAmber
class node_dbus_pcap,node_dbus_vis,node_dbus_view toneMint
class node_pretty_journal,node_check_journal,node_nginx_analysis toneRose
class node_reboot,node_reboot_pp,node_netboot,node_prepare_emmc,node_pldm_pdrdump toneIndigo
class node_openbmctool,node_witherspoon_debug,node_overlay toneTeal
```

## Components

### OpenBMC tools

Repository-wide collection of mostly independent operator and developer utilities.

- **Toolbox**: repo collection · Loose federation of independent OpenBMC utilities and scripts.

### Hardware tools

Utilities for ADC, PWM/tach, I2C, and sensor configuration.

- [ADC app](https://github.com/openbmc/openbmc-tools/tree/master/adcapp): C tool · Reads ADC values from device interfaces and reports them. · `adcapp`
- [PWM/tach](https://github.com/openbmc/openbmc-tools/tree/master/pwmtachtool): C tool · Interacts with PWM and tachometer control paths. · `pwmtachtool`
- [bi2cp](https://github.com/openbmc/openbmc-tools/tree/master/bi2cp): I2C tool · Low-level I2C access utility for board hardware inspection. · `bi2cp`
- [I2C tree](https://github.com/openbmc/openbmc-tools/blob/master/i2c/tree.py): Python script · Prints or analyzes I2C topology and bus relationships. · `i2c/tree.py`
- [Sensor config](https://github.com/openbmc/openbmc-tools/blob/master/sensor_yaml_config/sensor_yaml_config.py): Python tool · Transforms or generates sensor YAML configuration mappings. · `sensor_yaml_config/sensor_yaml_config.py`

### D-Bus analysis

Capture and visualization pipeline for OpenBMC bus activity.

- [dbus-pcap](https://github.com/openbmc/openbmc-tools/tree/master/dbus-pcap): capture tool · Captures D-Bus traffic into packet-capture form. · `dbus-pcap`
- [dbus-vis](https://github.com/openbmc/openbmc-tools/tree/master/dbus-vis): JS frontend · Browser UI that visualizes captured D-Bus and IPMI timelines. · `dbus-vis`
- [dbusView](https://github.com/openbmc/openbmc-tools/blob/master/dbusView/dbusView.py): Python viewer · Alternative viewer for D-Bus capture artifacts. · `dbusView/dbusView.py`

### Logs and diagnostics

Post-processing tools for journald, nginx logs, and similar artifacts.

- [pretty-journal](https://github.com/openbmc/openbmc-tools/blob/master/pretty-journal/pretty-journal.py): log formatter · Pretty-prints or normalizes journald output. · `pretty-journal/pretty-journal.py`
- [check_journal](https://github.com/openbmc/openbmc-tools/tree/master/check_journal/check_journal): log checker · Checks journal output for expected conditions or regressions. · `check_journal/check_journal`
- [nginx logs](https://github.com/openbmc/openbmc-tools/tree/master/nginx-log-analysis/analyze-nginx-log): analysis script · Analyzes nginx log files and emits summaries. · `nginx-log-analysis/analyze-nginx-log`

### Boot workflows

Reboot, netboot, and bring-up helpers for boards and QEMU.

- [reboot](https://github.com/openbmc/openbmc-tools/blob/master/reboot/reboot.sh): shell workflow · Automates reboot or validation steps via board-side scripting. · `reboot/reboot.sh`
- [ping-pong](https://github.com/openbmc/openbmc-tools/tree/master/reboot-ping-pong/rpp): reboot test · Exercises reboot timing or availability through repeated checks. · `reboot-ping-pong/rpp`
- [netboot](https://github.com/openbmc/openbmc-tools/tree/master/netboot/netboot): boot helper · Supports network boot and bring-up flows. · `netboot/netboot`
- [eMMC prep](https://github.com/openbmc/openbmc-tools/tree/master/prepare-emmc-qemu/prepare-emmc-qemu): QEMU helper · Prepares emmc-based QEMU or test images for boot workflows. · `prepare-emmc-qemu/prepare-emmc-qemu`
- [pdrdump](https://github.com/openbmc/openbmc-tools/blob/master/pldm/pdrdump.sh): PLDM script · Dumps PLDM PDR data for bring-up and diagnostics. · `pldm/pdrdump.sh`

### BMC CLI and debug

Interactive tools for querying and debugging OpenBMC systems.

- [openbmctool](https://github.com/openbmc/openbmc-tools/blob/master/openbmctool/openbmctool.py): Python CLI · Primary command-line client for interacting with OpenBMC. · `openbmctool/openbmctool.py`
- [witherspoon-debug](https://github.com/openbmc/openbmc-tools/tree/master/witherspoon-debug/debug): board debug · Platform-specific debugging utility for a board family. · `witherspoon-debug/debug`
- [overlay](https://github.com/openbmc/openbmc-tools/tree/master/overlay/overlay): debug helper · Specialized overlay or support script for platform debugging. · `overlay/overlay`

### Workflow automation

Repository and review workflow tools plus release automation.

- [tof-voters](https://github.com/openbmc/openbmc-tools/tree/master/tof-voters/libvoters): workflow tool · Analyzes Gerrit reviews and commits against acceptance patterns. · `tof-voters/libvoters`
- [cla-signers](https://github.com/openbmc/openbmc-tools/blob/master/cla-signers/update-cla.sh): workflow script · Manages CLA signer data for contribution workflow. · `cla-signers/update-cla.sh`
- [autobump](https://github.com/openbmc/openbmc-tools/blob/master/openbmc-autobump/openbmc-autobump.py): release automation · Automates version or dependency bumping tasks. · `openbmc-autobump/openbmc-autobump.py`

### Transform helpers

Small utilities that convert or validate structured data.

- [autojson](https://github.com/openbmc/openbmc-tools/blob/master/autojson/autojson.py): converter · Converts data to JSON or helper formats. · `autojson/autojson.py`
- [format-yaml](https://github.com/openbmc/openbmc-tools/blob/master/format-yaml/format-yaml.py): formatter · Formats YAML files or structured YAML content. · `format-yaml/format-yaml.py`
- [JSON checker](https://github.com/openbmc/openbmc-tools/tree/master/expectedJsonChecker): validator · Compares produced JSON against expected output. · `expectedJsonChecker`
- [ddconvnotrunc](https://github.com/openbmc/openbmc-tools/tree/master/ddconvnotrunc/ddconvnotrunc): conversion helper · Transforms captured data while preserving full record boundaries. · `ddconvnotrunc/ddconvnotrunc`

## Connections

- Toolbox → ADC app: contains · Top-level tool directory.
- Toolbox → PWM/tach: contains · Top-level tool directory.
- Toolbox → bi2cp: contains · Top-level tool directory.
- Toolbox → I2C tree: contains · Top-level tool directory.
- Toolbox → Sensor config: contains · Top-level tool directory.
- Toolbox → dbus-pcap: contains · Top-level tool directory.
- Toolbox → dbus-vis: contains · Top-level tool directory.
- Toolbox → dbusView: contains · Top-level tool directory.
- Toolbox → pretty-journal: contains · Top-level tool directory.
- Toolbox → check_journal: contains · Top-level tool directory.
- Toolbox → nginx logs: contains · Top-level tool directory.
- Toolbox → reboot: contains · Top-level tool directory.
- Toolbox → ping-pong: contains · Top-level tool directory.
- Toolbox → netboot: contains · Top-level tool directory.
- Toolbox → eMMC prep: contains · Top-level tool directory.
- Toolbox → openbmctool: contains · Top-level tool directory.
- Toolbox → witherspoon-debug: contains · Top-level tool directory.
- Toolbox → overlay: contains · Top-level tool directory.
- Toolbox → tof-voters: contains · Top-level tool directory.
- Toolbox → cla-signers: contains · Top-level tool directory.
- Toolbox → autobump: contains · Top-level tool directory.
- Toolbox → autojson: contains · Top-level tool directory.
- Toolbox → format-yaml: contains · Top-level tool directory.
- Toolbox → JSON checker: contains · Top-level tool directory.
- Toolbox → ddconvnotrunc: contains · Top-level tool directory.
- Toolbox → pdrdump: contains · Top-level tool directory.
- dbus-pcap → dbus-vis: capture -> view · Captured bus traffic is loaded into visualization tools.
- dbus-pcap → dbusView: capture -> view · Capture artifacts can also be inspected with the Python viewer.
- dbus-vis → dbus-pcap: loads · Visualization frontend consumes pcap-like capture output.
- dbus-vis → ddconvnotrunc: parses · Frontend includes loaders/parsers for captured data.
- pretty-journal → check_journal: normalizes · Log formatting feeds log checking and validation.
- reboot → ping-pong: drives · Reboot scripting supports repeated availability checks.
- reboot → netboot: boot flow · Reboot workflows and network boot both support bring-up.
- eMMC prep → netboot: prepares · Image preparation supports boot execution paths.
- openbmctool → dbus-pcap: talks via · Client-facing OpenBMC interaction ultimately traverses D-Bus surfaces.
- openbmctool → witherspoon-debug: complements · General CLI and platform-specific debug utilities overlap operationally.
- tof-voters → cla-signers: workflow · Both target developer governance and contribution workflows.
- tof-voters → autobump: automation · Repository automation tools cluster around maintenance workflows.
- autojson → format-yaml: transforms · Both are small conversion/formatting helpers.
- autojson → JSON checker: validates · Generated structured output can be checked against expectations.
- ADC app → Sensor config: configures · Sensor configuration and ADC reporting are closely related hardware surfaces.
- PWM/tach → bi2cp: hardware access · Both are low-level hardware-facing utilities.
- I2C tree → bi2cp: maps · I2C topology tooling complements raw bus access.
- pdrdump → openbmctool: diagnostics · Both support operator workflows around BMC state inspection.