diff --git a/documentation/builders/README.md b/documentation/builders/README.md index 3d70bca15..86e98aca1 100644 --- a/documentation/builders/README.md +++ b/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) diff --git a/documentation/builders/cli-client.md b/documentation/builders/cli-client.md new file mode 100644 index 000000000..b75e942ee --- /dev/null +++ b/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 + +* +* diff --git a/documentation/builders/rpc-commands.md b/documentation/builders/rpc-commands.md index f98da8cb4..374c27d97 100644 --- a/documentation/builders/rpc-commands.md +++ b/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 diff --git a/documentation/builders/system.md b/documentation/builders/system.md index 0e2c19485..e981678c0 100644 --- a/documentation/builders/system.md +++ b/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 ``` diff --git a/documentation/developers/README.md b/documentation/developers/README.md index 6c973d6ba..64fee44c1 100644 --- a/documentation/developers/README.md +++ b/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) diff --git a/documentation/developers/coreapps.md b/documentation/developers/coreapps.md index 3e4fc7b1f..4af784d50 100644 --- a/documentation/developers/coreapps.md +++ b/documentation/developers/coreapps.md @@ -8,7 +8,6 @@ $ cd src/jukebox $ ./ -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,7 +27,7 @@ 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). @@ -37,21 +35,20 @@ Will also setup equalizer and mono down mixer in the pulseaudio config file. Run **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. diff --git a/documentation/developers/libzmq.md b/documentation/developers/libzmq.md index 3407d971e..a9d26991a 100644 --- a/documentation/developers/libzmq.md +++ b/documentation/developers/libzmq.md @@ -4,12 +4,12 @@ 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 +* > [!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. @@ -17,13 +17,17 @@ If you need to update the `libzmq` version in the future, follow these steps. 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,7 +40,9 @@ 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 @@ -44,7 +50,7 @@ wget https://github.com/zeromq/libzmq/releases/download/v${ZMQ_VERSION}/zeromq-$ 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 ``` diff --git a/documentation/developers/pyhton.md b/documentation/developers/pyhton.md index 31659ef3c..5b2172c5c 100644 --- a/documentation/developers/pyhton.md +++ b/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 ``` diff --git a/src/cli_client/pbc.c b/src/cli_client/pbc.c index 8dcc462cb..44b6013fa 100644 --- a/src/cli_client/pbc.c +++ b/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: