Add docs for command line client for RPC (#2162)

* fix typos and add docs for pbc

* fix typo and fix markdown warnings

* move cli docs to builders

* move cli client to builders

* fix markdown warnings

documentation/builders/README.md

@@ -19,6 +19,8 @@
 * [Auto Hotspot](./autohotspot.md)
 * [Concepts](./concepts.md)
 * [System](./system.md)
+* [RPC Commands](./rpc-commands.md)
+* [CLI Client for RPC](./cli-client.md)
 * [Feature Status](../developers/status.md)
 * [Known Issues](../developers/known-issues.md)
 * [Developer Reference](../developers/README.md)

documentation/builders/cli-client.md

@@ -0,0 +1,21 @@
+# CLI Client
+
+The CLI (command line interface) client can be used to send [RPC commands](./rpc-commands.md) from command line to Phoniebox.
+
+## Installation
+
+* Install prerequisites: `sudo apt-get install libczmq-dev`
+* Change to directory: `cd ~/RPi-Jukebox-RFID/src/cli_client`
+* Compile CLI client: `gcc pbc.c -o pbc -lzmq -Wall`
+
+## Usage
+
+* Get help info: `./pbc -h`
+* Example shutdown: `./pbc -p host -o shutdown`
+
+See also [RPC Commands](./rpc-commands.md) reference.
+
+## Reference
+
+* <https://zeromq.org/>
+* <https://www.jsonrpc.org/specification>

documentation/builders/rpc-commands.md

@@ -1,6 +1,5 @@
 # RPC Commands
 
-
 We use the RPC commands when triggering actions from different inputs like a card swipe,
 a GPIO button press, etc. Triggering an action is equal to sending an RPC function call.
 In many places the command to send when an input is triggered is configurable in a YAML-file.
@@ -37,7 +36,6 @@ The keyword ``method`` is optional. If needs to be used depends on the function
 
 ## Aliases
 
-
 Not so complicated, right? It will get even easier. For common commands we have defined aliases. An alias simply maps
 to a pre-defined RPC command, e.g. ``play_card`` maps to ``player.ctrl.play_card``.
 
@@ -98,11 +96,9 @@ do exactly the same, but use different ways of specifying the command.
         folder: path/to/folder
         recursive: True
 
-
 .. important:: *args* must be a **list** of arguments to be passed! Even if only a single argument is passed.
     So, use *args: [value]*. We try catch mis-uses but that might not always work.
 
-
 You will find some more examples the configuration of the [Card Database](card-database.md)
 
 ## For developers

documentation/builders/system.md

@@ -46,7 +46,7 @@ $ journalctl --user -b -u mpd
 
 The `systemd` service file is located at the default location for user services:
 
-```
+```text
 /usr/lib/systemd/user/mpd.service
 ```
 
@@ -62,7 +62,7 @@ There is a number of reasons for that:
 
 The PulseAudio configuration file is located at
 
-```
+```text
 ~/.config/pulse/default.pa
 ```
 
@@ -90,7 +90,7 @@ $ journalctl --user -b -u jukebox-daemon
 
 The `systemd` service file is located at the default location for user services:
 
-```
+```text
 /usr/lib/systemd/user/jukebox-daemon.service
 ```
 
@@ -100,12 +100,12 @@ Starting and stopping the service can be useful for debugging or configuration c
 
 The Web UI is served using nginx. Nginx runs as a system service. The home directory is localed at
 
-```
+```text
 ./src/webapp/build
 ```
 
 The Nginx configuration is located at
 
-```
+```text
 /etc/nginx/sites-available/default
 ```

documentation/developers/README.md

@@ -11,3 +11,9 @@
 * [RFID Readers](./rfid)
 * [Feature Status](./status.md)
 * [Known Issues](./known-issues.md)
+
+## RPC
+
+* [LibZMQ](./libzmq.md)
+* [CLI Client for RPC](../builders/cli-client.md)
+* [RPC Commands](../builders/rpc-commands.md)

documentation/developers/coreapps.md

@@ -8,7 +8,6 @@ $ cd src/jukebox
 $ ./<scriptname> -h
 ```
 
-
 ## Jukebox Core
 
 **Scriptname:** [run_jukebox.py](../../src/jukebox/run_jukebox.py)
@@ -19,7 +18,6 @@ Usually this runs as a service, which is started automatically after boot-up. At
 
 For debugging, it is usually desirable to run the Jukebox directly from the console rather than as service. This gives direct logging info in the console and allows changing command line parameters. See [Troubleshooting](../builders/troubleshooting.md).
 
-
 ## Configuration Tools
 
 Before running the configuration tools, stop the Jukebox Core service.
@@ -29,29 +27,28 @@ See [Best practice procedure](../builders/configuration.md#best-practice-procedu
 
 **Scriptname:** [run_configure_audio.py](../../src/jukebox/run_configure_audio.py)
 
-Setup tool to register the PulseAudio sinks as primary and secondary audio outputs. 
+Setup tool to register the PulseAudio sinks as primary and secondary audio outputs.
 
 Will also setup equalizer and mono down mixer in the pulseaudio config file. Run this once after installation. Can be re-run at any time to change the settings. For more information see [Audio Configuration](../builders/audio.md).
 
 ### RFID Reader
 
 **Scriptname:** [run_register_rfid_reader.py](../../src/jukebox/run_register_rfid_reader.py)
 
-Setup tool to configure the RFID Readers. 
+Setup tool to configure the RFID Readers.
 
 Run this once to register and configure the RFID readers with the Jukebox. Can be re-run at any time to change the settings. For more information see [RFID Readers](./rfid/README.md).
 
 > [!NOTE]
 > This tool will always write a new configurations file. Thus, overwrite the old one (after checking with the user). Any manual modifications to the settings will have to be re-applied
 
-
 ## Developer Tools
 
 ### RPC
 
 **Scriptname:** [run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)
 
-Command Line Interface to the Jukebox RPC Server. 
+Command Line Interface to the Jukebox RPC Server.
 
 A command line tool for sending RPC commands to the running jukebox app. This uses the same interface as the WebUI. Can be used for additional control or for debugging.The tool features auto-completion and command history. The list of available commands is fetched from the running Jukebox service.
 

documentation/developers/libzmq.md

@@ -4,26 +4,30 @@
 
 The Jukebox requires `libzmq` to work properly. We provide downloadable builds to speed up the installation process of the Phoniebox.
 
-* https://github.com/pabera/libzmq/releases
+* <https://github.com/pabera/libzmq/releases>
 
 > [!NOTE]
 > We can't use stable builds that are distributed by [zeromq](https://github.com/zeromq/libzmq/releases) directly because the Jukebox requires draft builds to support WebSockets. These [draft builds](https://pyzmq.readthedocs.io/en/latest/howto/draft.html) are not officially provided through zeromq for Raspberry Pi architecture (e.g. `armv6` or `armv7`).
 
-## Building `libzmp`
+## Building `libzmq`
 
 If you need to update the `libzmq` version in the future, follow these steps.
 
 ### Install Cross-Compilation Environment
 
 First, you need to install Dockcross. Dockcross provides Docker images for cross-compilation.
 
-1. **Pull the Dockcross Image**: For Raspberry Pi B, 4 or Zero 2 we need `linux-armv7`, for older models `linux-armv6`. The following example shows how to compile for `armv7` (32 bit, `arm32v7`). If you want to compile for another target, change the commands accordingly. For Docker Development environments, other targets like `arm64` or `x86_64` become relevant.
+#### 1. Pull the Dockcross Image
+
+For Raspberry Pi B, 4 or Zero 2 we need `linux-armv7`, for older models `linux-armv6`. The following example shows how to compile for `armv7` (32 bit, `arm32v7`). If you want to compile for another target, change the commands accordingly. For Docker Development environments, other targets like `arm64` or `x86_64` become relevant.
 
 ```bash
 docker pull dockcross/linux-armv7
 ```
 
-3. **Create a Dockcross Script**: After pulling the image, you create a Dockcross script which will be used to run the cross-compilation tools in the Docker container.
+#### 2. Create a Dockcross Script
+
+After pulling the image, you create a Dockcross script which will be used to run the cross-compilation tools in the Docker container.
 
 ```bash
 docker run --rm dockcross/linux-armv7 > ./dockcross-linux-armv7
@@ -36,15 +40,17 @@ This command creates a script named `dockcross-linux-armv7` in your current dire
 
 With Dockcross installed, you can now modify your `libzmq` compilation process to use the Dockcross environment.
 
-1. **Download `libzmq` Source**: Similar to your original process, download the `libzmq` source code:
+#### 1. Download `libzmq` Source
+
+Similar to your original process, download the `libzmq` source code:
 
 ```bash
 ZMQ_VERSION=4.3.5
 wget https://github.com/zeromq/libzmq/releases/download/v${ZMQ_VERSION}/zeromq-${ZMQ_VERSION}.tar.gz -O libzmq.tar.gz
 tar -xzf libzmq.tar.gz
 ```
 
-2. **Cross-Compilation using Dockcross**:
+#### 2. Cross-Compilation using Dockcross
 
 Modify your build process to run inside the Dockcross environment:
 
@@ -61,8 +67,10 @@ make install DESTDIR=$(pwd)/../installed'
 
 This command configures and builds `libzmq` inside the Docker container. The `DESTDIR` variable is used to specify where to install the files inside the container.
 
-3. **Compress the Compiled Binaries**: After compilation, the binaries are located in the `installed` directory inside your `zeromq-${ZMQ_VERSION}` directory.
+#### 3. Compress the Compiled Binaries
 
-```
+After compilation, the binaries are located in the `installed` directory inside your `zeromq-${ZMQ_VERSION}` directory.
+
+```bash
 tar -czvf libzmq5-armv7-${ZMQ_VERSION}.tar.gz -C installed/usr/local --exclude='.' include lib
 ```

documentation/developers/pyhton.md

@@ -7,12 +7,12 @@
 
 Before you can run Python code, you need to enable the virtual environment. On the Raspberry Pi, it's located in the project root `~/RPi-Jukebox-RFID/.venv`. Depending on your setup, the absolute path can vary.
 
-```
+```bash
 $ source ~/RPi-Jukebox-RFID/.venv/bin/activate
 ```
 
 If the virtual environment has been activated correctly, your terminal will now show a prefix (`.venv`). If you want to leave the venv again execute deactivate.
 
-```
+```bash
 $ deactivate
 ```

src/cli_client/pbc.c

@@ -28,7 +28,7 @@
 
     pbc -> PhonieBox Command line interface
 
-    depenmds on libczmq:
+    depends on libczmq:
     apt-get install libczmq-dev
 
     how to compile: