Flesh out documentation

Some crtitical installation information was missing and I tried to add
some more explicit information about the different components.

Closes #10, #12

.gitignore

@@ -10,3 +10,7 @@ appliance-application/packages/preload/dist
 appliance-application/packages/renderer/dist
 package-lock.json
 __pycache__
+
+env/
+test-env/
+venv/

README.md

@@ -4,5 +4,17 @@ This software system is used to connect media devices inside a room to a BigBlue
 This allows to streamline the experience of online users by capturing the best media devices of the room (microphones, cameras).
 It also improves the experience for the in-site audience, by displaying the most relevant content, given the available displays.
 
+⚠ This project is a prototype to showcase the capabilities of BBB in a hybrid setting.
+It obviously misses a lot of features and *will* break in any kind of production setting.
+
 ## Architecture
+
+The system consists of three software components that need to be run and configured in order to work:
+
+1. The [room appliance application](appliance-application) needs to be run on a device (like Intel NUC) that connects to the room's audiovisual input and output devices. It holds the room configuration, i.e. how the media devices should be used in BBB and displays a PIN number that is used to pair the room with a BBB meeting.
+2. The [BBB HTML Plugin](html-plugin) is where you enter the PIN number displayed on the appliance to connect the running meeting to the room.
+3. The [pairing server](pairing-server) brokers the connection between the appliance in the room and the BBB meeting.
+
+Both the Plugin and the appliance application use the GraphQL interface of BBB 3 to communicate with BBB server.
+
 ![overview](https://github.com/bigbluebutton/bigbluebutton-room-media-connector/assets/4281791/577f1821-a246-4fbb-bdd8-49a888a8b053)

appliance-application/README.md

@@ -12,6 +12,14 @@ It also improves the experience for the in-site audience,
 by displaying the most relevant content, given the available
 displays.
 
+## Prerequisites
+
+This application needs to be run on a device (e.g. Intel NUC) inside the meeting room that
+itself can be connected to the room's audiovisual input and output devices.
+
+Currently as additional hardware an Elgato Streamdeck is required as input device if you
+want to control the meeting from the appliance.
+
 ## Running the application in development mode
 
 1. Copy config file:
@@ -25,7 +33,7 @@ Place the settings config file `settings.json` in the following folder:
 
 2. Customize the config file:
 
-- You have to adjust the `control_server.ws` setting to point to the location of the pairing server.
+- You have to adjust the `control_server.ws` setting to point to the `/ws_room` route of the pairing server (e.g. `https://your-bbb-server.org/hybrid/ws_room` if you follow the [instructions](../pairing-server/) and install the pairing server on a bbb host).
 - Next `room.name` should be set to the name of the room that should be shown during the pairing process.
 - You can also set `preferred_pin_screen` to the name of the screen that should be used to display the pairing pin. If the screen it not found, it uses the first screen it finds.
 - Lastly you need to define the layouts, a few examples are provided in `room.layouts`.

html-plugin/README.md

@@ -3,48 +3,63 @@
 
 ## What is it?
 
-This plugin communicates with the pairing server sending the user provided pin and receives the room layout config provided by the appliance application.
-It then creates the required join urls and passes it to the appliance application.
+This is a [BBB HTML plugin](https://github.com/bigbluebutton/bigbluebutton-html-plugin-sdk) where the user can enter the PIN displayed by the [room appliance application](../appliance-application/).
+It then checks this PIN with the [pairing-server](../pairing-server/) and afterwards creates the join-URLs for the applicance application.
 To finish the pairing it shows the pairing pin for user confirmation.
 
-## Running the Plugin from Source
+## Usage
 
-1. Start the development server:
+This is a general instruction on how to use a plugin.
+For a detailed configuration example of each use case,
+have a look at the READMEs in the respective [samples](samples)-folders.
 
-```bash
-npm install
-npm start
-```
+### Running the Plugin from Source
 
-2. Add reference to it on BigBlueButton's `settings.yml`:
+For development purposes you can run the plugin locally from source:
 
-```yaml
-  plugins:
-    - name: RoomMediaPlugin
-      url: http://127.0.0.1:4701/static/RoomMediaPlugin.js
-```
+1. Start the development server:
+    ```bash
+    cd $HOME/src/bigbluebutton-html-plugin-sdk/samples/sample-action-button-dropdown-plugin
+    npm install
+    npm start
+    ```
 
-## Building the Plugin
+2. Configure it in the `settings.yml` of the BBB HTML5 Client:
+    ```yaml
+    public:
+      plugins:
+        - name: RoomMediaPlugin
+          url: http://127.0.0.1:4701/static/RoomMediaPlugin.js
+    ```
 
-To build the plugin for production use, follow these steps:
+_N.B.:_ Be aware that in this case the url is interpreted from the plugin in the browser,
+so the localhost is actually your local development machine.
+
+### Building the Plugin
+
+To build the plugin for deployment follow these steps:
 
 ```bash
+cd $HOME/html-plugin
 npm install
 npm run build-bundle
 ```
 
-The above command will generate the `dist` folder, containing the bundled JavaScript file named `RoomMediaPlugin.js`. This file can be hosted on any HTTPS server.
+The above command will generate the `dist` folder, containing the bundled JavaScript file named `RoomMediaPlugin.js`.
+This file can be hosted on any HTTPS server.
 
-To use the plugin with BigBlueButton, add the plugin's URL to `settings.yml` as shown below:
+To use the plugin with BigBlueButton, add the plugin's URL to the `settings.yml` of the BBB HTML5 Client as shown below:
 
 ```yaml
 public:
-  app:
-    ... // All app configurations
   plugins:
     - name: RoomMediaPlugin
       url: <<PLUGIN_URL>>
-  ... // All other configurations
 ```
 
-Alternatively, you can host the bundled file on the BigBlueButton server by copying `dist/RoomMediaPlugin.js` to the folder `/var/www/bigbluebutton-default/assets/plugins`. In this case, the `<<PLUGIN_URL>>` will be `https://<your-host>/plugins/RoomMediaPlugin.js`.
+#### Hosting the Plugin on a BBB Server
+
+While the plugin can be hosted on any Server, it is also possible to host the bundled file directly on
+a BigBlueButton server.
+For that you copy the `dist/RoomMediaPlugin.js` to the folder `/var/www/bigbluebutton-default/assets/plugins`.
+In this case, the `<<PLUGIN_URL>>` above will be `https://<your-host>/plugins/RoomMediaPlugin.js`.

pairing-server/README.md

@@ -2,37 +2,34 @@
 
 ## What is it?
 
-This pairing server helps the [BigBlueButton Room Integration Plugin](https://github.com/bigbluebutton/bigbluebutton-room-media-connector) to connect the device that is installed in a physical lecture room into the BigBlueButton meeting.
-
-The device in the physical lecture room runs an electron app that is able to connect to BigBlueButton.
+This pairing brokers the connection between the [BBB HTML plugin](../html-plugin/) and the [appliance application](../appliance-application/)
+to connect the device that is installed in a physical lecture room into the running BigBlueButton meeting.
 
 ## Running the Server from source
 
-1. Install python3 venv
-
-```bash
-apt-get install python3-venv
-```
-
-2. Create a python3 virtual environment:
+First, create a python virtual environment and install the dependencies with pip:
 
 ```bash
 python3 -m venv env
-```
-
-3. Activate the virtual environment and install dependencies
-
-```bash
 . env/bin/activate
 pip install -r requirements.txt
 ```
 
-4. run the server
+Then you can run the server for testing purposes using:
+
 ```bash
 quart run
 ```
 
-If you want to use it with the plugin, you need to proxy this from a webserver with a valid SSL certificate as both the browser as well as the electron app won't connect.
+
+### Connecting to the other Components
+
+The communication with the BBB server requires TLS.
+So in order to get this to work with the HTML plugin and the appliance application you need to proxy
+the pairing server with a webserver with a valid SSL certificate.
+
+You can e.g. run the pairing server on an existing BigBlueButton server.
+In this case you just add a file `/etc/bigbluebutton/nginx/hybrid.nginx` with the following contents on the BBB server:
 
 ```nginx
 location /hybrid {
@@ -45,18 +42,25 @@ location /hybrid {
 
 ## Running the Server in production
 
-You need only one room integration server per BigBlueButton cluster. So this software does not need to run on a BigBlueButton Server but it is not forbidden to do so.
+⚠ *Be aware that this project is currently a proof-of-concept that is not yet suited to run in a real production environment.*
+
+You need only one room integration server per BigBlueButton cluster.
+So this software does not need to run on a BigBlueButton Server but it is not forbidden to do so.
 
 To run it in production, you can use any ASGI compatible application server such as hypercorn.
 
 ## Running tests
 
-1. Install test dependencies
+Install the test dependencies in a virtual environment:
+
 ```bash
-. env/bin/activate
+python3 -m venv test-env
+. test-env/bin/activate
 pip install -r requirements-test.txt
 ```
-2. Execute tests
+
+Then you can execute the tests with:
+
 ```bash
 python -m pytest
 ```