WebCFace

Web-based IPC & Dashboard-like UI

ROS1のようなプロセス間通信と、GUIによるデータの可視化や関数呼び出しができるシステムです。

C++ (C++17以上), C, Python (3.8以上), JavaScript/TypeScript で相互に数値、文字列、画像などのデータを送受信したり、関数を呼び出したりすることができます。

Linux, MacOS, Windows(MSVC, MinGW, MSYS2, Cygwin) で動作します。

Features

Easy to Setup

WebCFaceはサーバー側のプログラム webcface-server と、 クライアントライブラリで構成されています。
使い方はサーバーを起動し、クライアントライブラリを利用したプログラムを起動するだけです。 ROSのようなワークスペース管理機能はなく、どんなフレームワークのプロジェクトにも簡単に組み込むことができます。

C / C++ の場合、WebCFaceのライブラリは CMake を使っていれば find_package(webcface)、 pkg-config ならpkg-config --cflags --libs webcface で簡単に利用できます。
またライブラリ本体は

• Linux: libwebcface.so.<version>
• Mac: libwebcface.<version>.dylib
• Windows: webcface-<version>.dll (Release) or webcfaced-<version>.dll (Debug)

の1つのみであり、手動でこのライブラリにリンクして使うこともできます。
WebCFace内部では外部ライブラリを多数使用していますが、それらはシンボルをすべて非公開にしているのでユーザーが使用するライブラリとは干渉しません。 (WebCFaceをソースからビルドした場合と、brewでインストールした場合を除く)

Python, JavaScript には PyPI / npm に webcface パッケージを用意しているのでそれをインストールするだけで使えます。 通信にWebSocketを使用しているため、Webブラウザ上でもそのまま動作します。

少し難易度は上がりますが、CのAPIを経由することで他の言語からも使用できると思います。

Inter-Process Communication

WebCFaceの通信にはWebSocketとMessagePackを使っています。 このためプロセス間だけでなくWebブラウザーとの通信が可能になっています。 さらに同一マシン上やDocker,WSL経由など使用可能な場合はTCPの代わりにUnixドメインソケットを使用します。

Wi-FiやEtherNet経由で複数のPC間(OS問わず)で通信することも可能です。 WindowsとWSL1/2の間の相互通信も自動的に接続されます。

WebCFaceで送受信できるデータ型として

• 数値型・数値配列型(Value)
• 文字列型(Text)
• 画像(Image)
• 関数呼び出し(Func)
• テキストログ(Log)

などの型が用意されています。 ユーザーがメッセージ型を定義できるROSやgRPCと比べると自由度は低いかもしれませんが、 これらのデータ型の組み合わせであれば簡単に送受信させることができます。

Image型データは送受信の過程で画像を縮小したりJPEGやPNGに圧縮したりといった操作をサーバー側で行うことができます。 表示目的など、圧縮した画像で十分な場合には簡単に通信量を削減できます。

WebCFaceの通信データ形式はOSやライブラリの言語によらず共通で、またバージョン間で後方互換性があります。 つまり、異なるバージョンのクライアント同士でも、異なるバージョンのOSでも問題なく通信が可能です。 (C++のver1.1.6以前を除く)
ただしそれぞれのクライアントのバージョンよりサーバーの方が新しいバージョンである必要があります。

WebUI

WebCFaceではプログラム間でデータの送受信ができるAPIだけでなく、 WebブラウザーからWebCFaceで通信されているデータを可視化したり関数を呼び出したりできるUI(WebUI)を提供します。

さらにボタンや入力欄などの並べ方をWebCFaceを使ったC++,Pythonなどのプログラムの側で定義してそれをWebUIに表示させることができ、 これによりHTMLやCSSの知識がなくても簡易なUIを作成することができます。

また、同様に2D、3Dの図形もWebCFaceを使ったプログラム側の記述のみでWebUIに描画させることができます。

なお、これらの描画データは View, Canvas2D, Canvas3D として他のデータ型(数値や文字列など)と同様にWebCFace内の通信データとして存在しており、 WebUI以外でもこれらのデータを受信して表示するアプリを作成することは可能です。

WebCFace-Tools

コマンドラインからWebCFaceのデータにアクセスできるコマンドもいくつか用意しています。

webcface-launcher は事前に登録しておいたコマンドの起動・停止をWebCFaceのViewから操作することができる機能です。 serverとlauncherだけを常時起動しておき、WebUIを使ってプログラムをリモートに操作するという使い方ができます。

webcface-tui はターミナル上で操作できるTUIアプリで、Webブラウザを開かなくてもデータをリアルタイムで確認したり、Viewの操作もできます。

Links

• webcface: サーバー & C/C++クライアントライブラリ (このリポジトリ)
• webcface-webui: webブラウザ用UIアプリ
• webcface-tools: コマンドラインツール群
• webcface-js: JavaScriptクライアントライブラリ
• webcface-python: Pythonクライアントライブラリ
• homebrew-webcface: HomebrewのTapを管理しています
• webcface-windows-package: Windows用ビルドをリリースする場所
• plogjuggler-webcface-plugin: PlotJuggler プラグイン

Installation

WebCFace ver1については v1ブランチ を参照してください。

ver2は以下のようにLinux,Windows,MacOS用にビルドしたアーカイブをダウンロードできます。

Ubuntu (x86_64, arm64, armhf)

webcface-package リポジトリから linux用のzipファイルをダウンロードし、任意の場所に展開してください。

• sudo権限が使える場合は /usr/local または /opt/webcface に展開するのがおすすめです。
• また、展開したディレクトリ内の bin/ をPATHに、 lib/*-linux-gnu*/pkgconfig/ をPKG_CONFIG_PATHに追加してください。
• さらにsystemdのサービスファイルを使用したい場合は /opt/webcface/lib/systemd/system に展開されたファイルに対して /etc/systemd/system/ にリンクを貼るなどしてください。

Ubuntu20.04でビルドしているため、それより古いUbuntuでは動作しません(ソースからビルドする必要があります)。 また、Ubuntu以外のディストリビューションで動作するかはわかりません。

ダウンロードと展開をコマンドラインでやるなら以下のようにします。 (/opt/webcface に展開し, 環境変数を ~/.bashrc に書き込みます。それ以外の環境の場合は適宜読み替えてください。)

x86_64

curl -fLO https://github.com/na-trium-144/webcface-package/releases/download/v2.3.0/webcface_2.3.0_linux_amd64.zip
sudo unzip webcface_2.3.0_linux_amd64.zip -d /opt/webcface
rm webcface_2.3.0_linux_amd64.zip
echo 'export PATH="/opt/webcface/bin:$PATH"' >> ~/.bashrc
echo 'export PKG_CONFIG_PATH="/opt/webcface/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bashrc
sudo ln -sf /opt/webcface/lib/systemd/system/*.service /etc/systemd/system/

arm64

curl -fLO https://github.com/na-trium-144/webcface-package/releases/download/v2.3.0/webcface_2.3.0_linux_arm64.zip
sudo unzip webcface_2.3.0_linux_arm64.zip -d /opt/webcface
rm webcface_2.3.0_linux_arm64.zip
echo 'export PATH="/opt/webcface/bin:$PATH"' >> ~/.bashrc
echo 'export PKG_CONFIG_PATH="/opt/webcface/lib/aarch64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bashrc
sudo ln -sf /opt/webcface/lib/systemd/system/*.service /etc/systemd/system/

armhf

curl -fLO https://github.com/na-trium-144/webcface-package/releases/download/v2.3.0/webcface_2.3.0_linux_armhf.zip
sudo unzip webcface_2.3.0_linux_armhf.zip -d /opt/webcface
rm webcface_2.3.0_linux_armhf.zip
echo 'export PATH="/opt/webcface/bin:$PATH"' >> ~/.bashrc
echo 'export PKG_CONFIG_PATH="/opt/webcface/lib/arm-linux-gnueabihf/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bashrc
sudo ln -sf /opt/webcface/lib/systemd/system/*.service /etc/systemd/system/

Deb Package (Ubuntu x86_64, arm64, armhf)

Debパッケージとしてビルドしたものを WebCFaceのReleases と webuiのReleases 、toolsのReleases からダウンロードしてインストールできます。 内容はzipアーカイブで配布しているものに加えて WebCFace Desktop のアプリケーションランチャーが含まれます。

Ubuntu20.04でビルドしているため、それより古いUbuntuでは動作しません(ソースからビルドする必要があります)。 また、Ubuntu以外のディストリビューションで動作するかはわかりません。

ダウンロードと展開をコマンドラインでやるなら以下のようにします。

x86_64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v2.3.0/webcface_2.3.0_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v2.0.1/webcface-tools_2.0.1_amd64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.8.3/webcface-webui_1.8.3_all.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.8.3/webcface-desktop_1.8.3_linux_amd64.deb
sudo apt install ./webcface*.deb
rm ./webcface*.deb

arm64

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v2.3.0/webcface_2.3.0_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v2.0.1/webcface-tools_2.0.1_arm64.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.8.3/webcface-webui_1.8.3_all.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.8.3/webcface-desktop_1.8.3_linux_arm64.deb
sudo apt install ./webcface*.deb
rm ./webcface*.deb

armhf

curl -fLO https://github.com/na-trium-144/webcface/releases/download/v2.3.0/webcface_2.3.0_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-tools/releases/download/v2.0.1/webcface-tools_2.0.1_armhf.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.8.3/webcface-webui_1.8.3_all.deb
curl -fLO https://github.com/na-trium-144/webcface-webui/releases/download/v1.8.3/webcface-desktop_1.8.3_linux_armv7l.deb
sudo apt install ./webcface*.deb
rm ./webcface*.deb

macOS

webcface-package リポジトリから macos用のzipファイルをダウンロードできますが、 署名や公証をしていないためブラウザーからダウンロードするとGatekeeperにブロックされてしまいます。 (開発元を検証できないため開けません。の画面になります)

以下のようにコマンドラインからダウンロード、展開することでGatekeeperを回避できます。

Universalバイナリになっており、IntelMacもAppleシリコンも共通です。 macOS 12 (Monterey) でビルドしているので、それより古いMacでは動かないかもしれません。

curl -fLO https://github.com/na-trium-144/webcface-package/releases/download/v2.3.0/webcface_2.3.0_macos_universal.zip
curl -fLO https://github.com/na-trium-144/webcface-package/releases/download/v2.3.0/webcface-desktop_2.3.0_macos_app.zip

sudo権限が使用できれば以下のように webcface_universal を /opt/webcface に、 webcface-desktop_app を /Applications に展開するのがおすすめです。

sudo unzip webcface_2.3.0_macos_universal.zip -d /opt/webcface
sudo unzip webcface-desktop_2.3.0_macos_app.zip -d /Applications
rm webcface_2.3.0_macos_universal.zip
rm webcface-desktop_2.3.0_macos_app.zip

また、展開したディレクトリ内の bin/ をPATHに、 lib/pkgconfig/ をPKG_CONFIG_PATHに追加してください。 (別の場所に展開した場合や、zsh以外の環境の場合は適宜読み替えてください)

echo 'export PATH="/opt/webcface/bin:$PATH"' >> ~/.zshrc
echo 'export PKG_CONFIG_PATH="/opt/webcface/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc

webcfaceライブラリはinstall_nameが /opt/webcface/lib のパスになっているため、それ以外の場所に展開した場合は export DYLD_LIBRARY_PATH="(webcfaceディレクトリのパス)/lib:$DYLD_LIBRARY_PATH" も必要になるかもしれません。

Homebrew (MacOS, Linux)

na-trium-144/webcface のtap からインストールできますが、 brewでビルドしたwebcfaceはsharedライブラリとして多数の依存ライブラリが必要になるのであまりおすすめしません。

また、brewでインストールした場合 WebCFace Desktop アプリは付属しません。

brew tap na-trium-144/webcface
brew install webcface webcface-webui webcface-tools

Windows MSVC

webcface-package リポジトリから windows用のexeファイルまたはzipファイルをダウンロードできます。 x86バージョンとx64バージョンがあります。 (ただしインストーラーと WebCFace Desktop アプリはどちらも32bitになっています)

• exeファイルは実行するとインストーラーが起動します。
  • 署名していないため Windows Defender にブロックされるかもしれません。 その場合は「詳細情報」→「実行」をクリックして実行してください。
  • インストール場所はデフォルトで C:\Program Files\webcface になります。(変更可能です)
  • また、自動的に環境変数のPATHが設定され、スタートメニューにも WebCFace Desktop のショートカットが追加されます。
  • アンインストールはコントロールパネルや設定アプリから他のアプリと同様にできます。
• zipファイルは任意の場所に展開して使用してください。
  • コマンドラインツールやライブラリを使う(Meson,CMakeでインポートする)には、展開したwebcfaceディレクトリの中の bin/ を手動で環境変数のPATHに追加する必要があります。
• 最新の Visual C++ 再頒布可能パッケージ がインストールされていない場合はインストールする必要があります。
• 比較的新しいWindows10以上であれば動作するはずです。古いWindowsでは動作確認していません。
• いずれも最新バージョンの Visual Studio 2019 でビルドしているため、それよりも古い Visual Studio からwebcfaceライブラリにリンクすると正常動作しないかもしれません。

MinGW用バイナリは今のところ配布していません(ソースからビルドしてください)

Documentation

DoxygenでAPIリファレンスとともにチュートリアル、ドキュメントを公開しています。

• 1 チュートリアル: Visualizing / Communication
• 2 Server / WebUI
• 3 クライアントライブラリのセットアップ / WebCFaceのソースからのビルド
• APIリファレンス
• webcface-python APIリファレンス
• webcface-js APIリファレンス

License

WebCFaceと関連するプログラムはすべてMITライセンスで公開しています。詳細は LICENSE を参照してください。

WebCFace本体とtoolsが使用しているサードパーティーのライブラリのライセンスはそれぞれ以下を参照してください。

• msgpack-c (Boost Software License) : https://github.com/msgpack/msgpack-c
• eventpp (Apache 2.0) : https://github.com/wqking/eventpp
• spdlog (MIT) : https://github.com/gabime/spdlog
• curl : https://curl.se/docs/copyright.html
• Asio (Boost Software License) : http://think-async.com/Asio/
• Crow (BSD 3-Clause) : https://github.com/CrowCpp/Crow
• CLI11 (BSD 3-Clause) : https://github.com/CLIUtils/CLI11
• UTF8-CPP (BSD 1.0) : https://github.com/nemtrif/utfcpp
• ImageMagick: https://imagemagick.org/script/license.php
• tiny-process-library (MIT) : https://gitlab.com/eidheim/tiny-process-library
• toml++ (MIT) : https://github.com/marzer/tomlplusplus
• FTXUI (MIT) : https://github.com/ArthurSonzogni/FTXUI