CanWeeb

English

This English section was translated with GPT-5.4. It may contain minor inaccuracies compared with the Japanese section below.

CanWeeb is a node-to-node communication system for robotics, sensors, tools, and interactive applications. It provides reliable control messaging, fast telemetry distribution, stream transfer, a built-in web API, real-time WebSocket updates, peer discovery, Wi-Fi control, and Raspberry Pi hardware integration through CmdLib.

Repository Overview

CanWeeb is the mesh runtime and communication layer.
CmdLib is the Raspberry Pi hardware-control library for GPIO, PWM, rotary encoders, ultrasonic sensors, overlays, and child-side helper processes.
PiHub is a related project for sending a PC screen to a Raspberry Pi over LAN, displaying it on HDMI, and exposing it as a web-viewable stream.

What You Can Do

Send reliable control messages between nodes with acknowledgment and persistence.
Publish fast-changing telemetry and keep the latest value per topic.
Transfer larger binary payloads as streams.
Integrate external applications through HTTP and WebSocket APIs.
Discover peers automatically on the local network.
Manage Wi-Fi mode and connectivity through the API.
Connect Raspberry Pi sensors and rotary encoders through CmdLib.
Build distributed examples such as Marrio and loli.

Communication Model

Traffic Class	Purpose
`control`	Reliable commands, events, and state changes with acknowledgment and persistence.
`telemetry`	Low-overhead sensor and status updates with latest-value caching.
`stream`	Chunked transfer for larger binary payloads.

Messages can be sent to a single node, multiple nodes, or broadcast across the mesh.

Web API

CanWeeb includes a built-in HTTP and WebSocket interface for integration, debugging, and monitoring.

Route	Function
`/api/status`	Read runtime state, queue counts, inbox counts, and peer status.
`/api/messages`	Send a new message.
`/api/inbox`	List received control messages.
`/api/inbox/:message_id`	Read one inbox item in detail.
`/api/topics`	List cached telemetry topics.
`/api/topic?name=...`	Read one telemetry topic.
`/api/streams`	List completed streams.
`/api/streams/:stream_id`	Read one completed stream.
`/api/peer-policies`	Read or update peer policy.
`/api/wifi/status`	Read Wi-Fi state.
`/api/wifi/apply-mode`	Apply Wi-Fi mode.
`/api/wifi/connect`	Connect to Wi-Fi.
`/api/wifi/disconnect`	Disconnect Wi-Fi.
`/api/wifi/hotspot/start`	Start hotspot mode.
`/api/wifi-direct/run`	Run a direct `wpa_cli` command.
`/ws/inbox`	Receive live inbox updates.
`/ws/topics`	Receive live telemetry updates.
`/ws/streams`	Receive live completed-stream updates.

Message Example

{
  "target": "node:peer-a",
  "traffic_class": "control",
  "topic": "example/topic",
  "subject": "example_event",
  "content_type": "application/json",
  "text": "{\"hello\":true}"
}

Node Runtime

A node can listen for incoming connections, connect to configured peers, discover peers over UDP broadcast, report status, dispatch outgoing messages, and clean up old state.

Storage

Control messages can be stored in queue and inbox directories under storage.root.
Telemetry keeps the latest value per topic in memory.
Streams are assembled and exposed as completed stream records.

CmdLib

CmdLib (canweeb_cmdlib) is a Rust library that provides hardware control APIs for Raspberry Pi. It runs entirely on the Pi without any external microcontroller, using /dev/gpiochip0 (gpio-cdev) and standard system commands.

DtOverlay — Device Tree Overlay Management

Load, unload, and inspect Raspberry Pi Device Tree Overlays via the dtoverlay command.

Method	Description
`DtOverlay::load(name, params)`	Load an overlay with optional key=value parameters.
`DtOverlay::unload(name)`	Unload a named overlay.
`DtOverlay::list()`	Return a list of currently loaded overlays.
`DtOverlay::is_loaded(name)`	Check whether an overlay is currently active.

DtOverlay::load("rotary-encoder", &[("relative_axis", "1"), ("steps-per-period", "1")])?;
DtOverlay::unload("rotary-encoder")?;

pinctrl — Pin Mode and Pull Configuration

Configure Raspberry Pi GPIO pin function and pull resistor state via the pinctrl utility.

Method	Description
`pinctrl_set(pin, mode, pull)`	Set a pin to input/output and configure pull-up/pull-down/none.
`pinctrl_get(pin)`	Read the current function and level of a pin.

pinctrl_set(17, PinMode::Input, Pull::Up)?;
let state = pinctrl_get(17)?;

GpioUltrasonicSensor — HC-SR04 Distance Measurement

Measure distance using an HC-SR04 ultrasonic sensor directly wired to GPIO pins. Applies median filtering over multiple samples and discards outliers.

Parameter	Description
`trigger_pin`	GPIO pin connected to HC-SR04 TRIG.
`echo_pin`	GPIO pin connected to HC-SR04 ECHO.
`samples`	Number of measurements to take for median filtering.

let sensor = GpioUltrasonicSensor::new(23, 24, 5)?;
let distance_cm = sensor.measure_cm()?;

GpioRotaryEncoder3Pin — Quadrature Rotary Encoder

Read a 3-pin quadrature rotary encoder directly from GPIO. Supports software debounce and atomic position reading from a background thread.

Parameter	Description
`pin_a`, `pin_b`	Two quadrature signal pins.
`pin_sw`	Optional push-button switch pin.
`debounce_us`	Minimum pulse width in microseconds to accept as valid.

let enc = GpioRotaryEncoder3Pin::new(17, 27, 22, 500)?;
let position = enc.position(); // i64, updated by background thread

PwmOutput — PWM Motor and Servo Control

Generate PWM signals for motors, servos, and other PWM-controlled devices via the Arduino-compatible backend abstraction.

Method	Description
`PwmOutput::new(pin)`	Create a PWM output on a pin (default 25 kHz).
`.frequency(hz)`	Set PWM frequency.
`.range(min%, max%)`	Clamp duty cycle range.
`.set_duty(percent)`	Apply duty cycle (0.0–100.0).

let mut pwm = PwmOutput::new(12).frequency(50);
pwm.set_duty(7.5)?; // 7.5% = servo center

RemoteExec — Child Program Execution

Define and spawn child-side programs through CmdLib. Useful for running sensor reader binaries managed by the CanWeeb runtime.

let child = RemoteExec::new("sensor-reader", &["/usr/bin/sensor-reader", "--port", "/dev/ttyUSB0"]);
child.spawn()?;

Runtime — Async Task Integration

CmdLib provides a Runtime handle to integrate hardware polling loops into a Tokio async runtime alongside the CanWeeb mesh tasks.

Examples

Marrio

A distributed game where a PC receives movement and jump events over CanWeeb.
Raspberry Pi A reads ultrasonic sensor data from Arduino over serial and sends jump events.
Raspberry Pi B reads a 3-pin rotary encoder through GPIO and sends left/right movement events.

marrio/input/jump
marrio/input/move

loli

*Note: Some student engineers in Japan jokingly refer to rotary encoders as `lolicon`.*

A Raspberry Pi sender reads a rotary encoder and publishes position updates through CanWeeb.
A Python visualizer receives updates through WebSocket and maps them to eight directions.
The sender uses DTOverlay, pinctrl, and direct GPIO encoder reading.

loli/encoder/position

Configuration

Section	Purpose
`[node]`	Node identity, role, and tags.
`[storage]`	Storage location and retention.
`[web]`	HTTP and WebSocket bind address.
`[transport]`	Network or USB listeners and timing.
`[discovery]`	Automatic peer discovery.
`[wifi]`	Wi-Fi interface, mode, and fallback networks.
`[[peers]]`	Known peer definitions.

[node]
node_id = "parent"
role = "parent"

[storage]
root = "./data/parent"

[web]
bind = "0.0.0.0:8080"

[transport]
network_listen = "0.0.0.0:7002"

Getting Started from Clone

git clone https://github.com/rintaro-s/CanWeeb.git
cd CanWeeb

cargo run --release --bin canweeb -- --config config/parent.toml

The main executable is canweeb. If you omit --config, the default config path in code is config/example.toml.

To start a second node with another configuration:

cargo run --release --bin canweeb -- --config config/child.toml

Repository Layout

CanWeeb/
- src/          # runtime, config, protocol, storage, web, wifi
- CmdLib/       # Raspberry Pi control library
- config/       # example node configurations
- examples/     # application examples including Marrio and loli
- docs/         # public documentation

日本語

CanWeeb は、ロボティクス、センサー、ツール、インタラクティブアプリケーション向けのノード間通信システムです。信頼性の高い制御メッセージ配送、高速な telemetry 配信、stream 転送、内蔵 Web API、リアルタイム WebSocket 更新、ピア discovery、Wi-Fi 制御、そして CmdLib による Raspberry Pi ハードウェア統合を提供します。

リポジトリ概要

CanWeeb は、メッシュ通信ランタイムと通信基盤です。
CmdLib は、GPIO、PWM、ロータリーエンコーダ、超音波センサ、overlay 操作、子側補助プロセス実行のための Raspberry Pi 向けハードウェア制御ライブラリです。
PiHub は、PC 画面を LAN 経由で Raspberry Pi に送り、Pi の HDMI に表示しつつ、Web ブラウザでも視聴できるようにする関連プロジェクトです。

何ができるか

ACK と永続化付きで、ノード間に信頼性の高い control メッセージを送れます。
変化の速い telemetry を配信し、トピックごとに最新値を保持できます。
大きなバイナリペイロードを stream として転送できます。
HTTP API と WebSocket API を通じて外部アプリと連携できます。
ローカルネットワーク上のピアを自動検出できます。
API 経由で Wi-Fi モードや接続状態を管理できます。
CmdLib を使って Raspberry Pi のセンサーやロータリーエンコーダを扱えます。
Marrio や loli のような分散アプリの構成を作れます。

通信モデル

トラフィッククラス	用途
`control`	ACK と永続化を伴う、コマンド、イベント、状態変更向けの信頼性重視通信です。
`telemetry`	最新値キャッシュ付きの、軽量なセンサー・状態更新向け通信です。
`stream`	大きなバイナリペイロード向けの分割転送です。

メッセージは単一ノード、複数ノード、またはメッシュ全体へのブロードキャストに送れます。

Web API

CanWeeb には、統合、デバッグ、監視のための HTTP / WebSocket インターフェースが内蔵されています。

ルート	機能
`/api/status`	ランタイム状態、キュー数、inbox 数、ピア状態を取得します。
`/api/messages`	新しいメッセージを送信します。
`/api/inbox`	受信済み control メッセージを一覧します。
`/api/inbox/:message_id`	1 件の inbox 詳細を取得します。
`/api/topics`	キャッシュ済み telemetry を一覧します。
`/api/topic?name=...`	1 件の telemetry topic を取得します。
`/api/streams`	完了済み stream を一覧します。
`/api/streams/:stream_id`	1 件の完了済み stream を取得します。
`/api/peer-policies`	ピアポリシーを取得または更新します。
`/api/wifi/status`	Wi-Fi 状態を取得します。
`/api/wifi/apply-mode`	Wi-Fi モードを適用します。
`/api/wifi/connect`	Wi-Fi に接続します。
`/api/wifi/disconnect`	Wi-Fi を切断します。
`/api/wifi/hotspot/start`	ホットスポットモードを開始します。
`/api/wifi-direct/run`	`wpa_cli` を直接実行します。
`/ws/inbox`	inbox のリアルタイム更新を受信します。
`/ws/topics`	telemetry のリアルタイム更新を受信します。
`/ws/streams`	完了済み stream の更新を受信します。

メッセージ送信例

{
  "target": "node:peer-a",
  "traffic_class": "control",
  "topic": "example/topic",
  "subject": "example_event",
  "content_type": "application/json",
  "text": "{\"hello\":true}"
}

ノードランタイム

ノードは、受信接続の待受、設定済みピアへの接続、UDP ブロードキャストによるピア検出、状態レポート、送信メッセージ配送、古い状態のクリーンアップを行えます。

ストレージ

control メッセージは storage.root 配下の queue と inbox に保存されます。
telemetry はトピックごとに最新値をメモリ保持します。
stream は組み立てられ、完了済み stream として参照できます。

CmdLib

CmdLib (canweeb_cmdlib) は、Raspberry Pi のハードウェアを制御するための Rust ライブラリです。外部マイコンは不要で、/dev/gpiochip0（gpio-cdev）とシステムコマンドのみで動作します。

DtOverlay — Device Tree Overlay 管理

dtoverlay コマンド経由で Raspberry Pi の DTOverlay をロード・アンロード・確認します。

メソッド	説明
`DtOverlay::load(name, params)`	オーバーレイを key=value パラメータ付きでロードします。
`DtOverlay::unload(name)`	指定オーバーレイをアンロードします。
`DtOverlay::list()`	現在ロード済みのオーバーレイ一覧を返します。
`DtOverlay::is_loaded(name)`	オーバーレイがアクティブかどうかを確認します。

DtOverlay::load("rotary-encoder", &[("relative_axis", "1"), ("steps-per-period", "1")])?;
DtOverlay::unload("rotary-encoder")?;

pinctrl — ピンモード・プル設定

pinctrl ユーティリティを使って GPIO ピンの機能とプル抵抗設定を行います。

関数	説明
`pinctrl_set(pin, mode, pull)`	ピンを入力/出力に設定し、プルアップ/プルダウン/なしを指定します。
`pinctrl_get(pin)`	現在のピン機能とレベルを読み取ります。

pinctrl_set(17, PinMode::Input, Pull::Up)?;
let state = pinctrl_get(17)?;

GpioUltrasonicSensor — HC-SR04 超音波距離測定

HC-SR04 超音波センサを GPIO に直結して距離を測定します。複数サンプルの中央値フィルタと外れ値除去を適用します。

パラメータ	説明
`trigger_pin`	HC-SR04 の TRIG に接続した GPIO ピン番号。
`echo_pin`	HC-SR04 の ECHO に接続した GPIO ピン番号。
`samples`	中央値フィルタのサンプル数。

let sensor = GpioUltrasonicSensor::new(23, 24, 5)?;
let distance_cm = sensor.measure_cm()?;

GpioRotaryEncoder3Pin — クアドラチャロータリーエンコーダ

3 ピンのクアドラチャロータリーエンコーダを GPIO 直結で読み取ります。ソフトウェアデバウンスとバックグラウンドスレッドによるアトミック位置更新に対応します。

パラメータ	説明
`pin_a`, `pin_b`	クアドラチャの 2 信号ピン。
`pin_sw`	プッシュスイッチのピン（省略可）。
`debounce_us`	有効と判定する最小パルス幅（マイクロ秒）。

let enc = GpioRotaryEncoder3Pin::new(17, 27, 22, 500)?;
let position = enc.position(); // i64、バックグラウンドスレッドが更新

PwmOutput — PWM モーター・サーボ制御

Arduino 互換の backend 抽象化を通じて、モーター・サーボ等の PWM デバイスを制御します。

メソッド	説明
`PwmOutput::new(pin)`	指定ピンに PWM 出力を作成します（デフォルト 25 kHz）。
`.frequency(hz)`	PWM 周波数を設定します。
`.range(min%, max%)`	デューティ比の範囲を制限します。
`.set_duty(percent)`	デューティ比を適用します（0.0〜100.0）。

let mut pwm = PwmOutput::new(12).frequency(50);
pwm.set_duty(7.5)?; // 7.5% = サーボ中央

RemoteExec — 子プログラム実行

CmdLib のヘルパーを使って子側プログラムを定義・起動します。CanWeeb ランタイムが管理するセンサーリーダーバイナリの実行に使用します。

let child = RemoteExec::new("sensor-reader", &["/usr/bin/sensor-reader", "--port", "/dev/ttyUSB0"]);
child.spawn()?;

Runtime — 非同期タスク統合

CmdLib は Runtime ハンドルを提供し、ハードウェアポーリングループを CanWeeb メッシュタスクと同じ Tokio 非同期ランタイムに統合できます。

サンプル

Marrio

PC 側が CanWeeb 経由で移動とジャンプを受信する分散ゲームです。
Raspberry Pi A は Arduino から超音波センサ値をシリアル受信し、ジャンプイベントを送ります。
Raspberry Pi B は 3 ピンロータリーエンコーダを GPIO で読み取り、左右移動イベントを送ります。

marrio/input/jump
marrio/input/move

loli

Raspberry Pi 側送信プログラムがロータリーエンコーダを読み取り、位置更新を CanWeeb に流します。
Python ビジュアライザが WebSocket で更新を受信し、8 方向に変換して表示します。
送信側は DTOverlay、pinctrl、GPIO 直接読み取りを使用します。

loli/encoder/position

設定

セクション	用途
`[node]`	ノード識別、役割、タグです。
`[storage]`	保存先と保持期間です。
`[web]`	HTTP・WebSocket の待受アドレスです。
`[transport]`	ネットワーク・USB 待受とタイミングです。
`[discovery]`	自動ピア検出です。
`[wifi]`	Wi-Fi インターフェース、モード、fallback 設定です。
`[[peers]]`	既知ピア定義です。

[node]
node_id = "parent"
role = "parent"

[storage]
root = "./data/parent"

[web]
bind = "0.0.0.0:8080"

[transport]
network_listen = "0.0.0.0:7002"

クローンから始める

git clone https://github.com/rintaro-s/CanWeeb.git
cd CanWeeb

cargo run --release --bin canweeb -- --config config/parent.toml

メイン実行ファイルは canweeb です。--config を省略した場合、コード上のデフォルトは config/example.toml です。

別設定で 2 台目のノードを起動する場合:

cargo run --release --bin canweeb -- --config config/child.toml

リポジトリ構成

CanWeeb/
- src/          # runtime, config, protocol, storage, web, wifi
- CmdLib/       # Raspberry Pi control library
- config/       # example node configurations
- examples/     # application examples including Marrio and loli
- docs/         # public documentation