Improve guidance on development/testing

Readme.md

@@ -19,7 +19,7 @@ The application layer may be defined in a single Nix file.
 
 This repository contains the application layer for running the Dividat Play web app and supporting system services in a fullscreen kiosk.
 
-See the [documentation](docs/arch) for more information.
+See the [documentation](docs/arch) and [user manual](docs/user-manual) for more information.
 
 ## Quick start
 
@@ -43,24 +43,70 @@ For example: `nix build --arg buildInstaller false --arg buildBundle false` will
 
 A virtual machine (with test instrumentation) can be started without any of the above builds.
 
-### Virtual machine
+## Components
 
-A helper is available to quickly start a virtual machine:
+### Controller
 
-```
+The [controller](controller/) service orchestrates the system's self-update and acts as a configuration interface for the options exposed to the user. It may be run directly on a Linux host for development purposes.
+
+### Kiosk
+
+The [kiosk](kiosk/) browser is used in the default configuration of PlayOS to run any web application in a full screen kiosk. It can be run directly on most hosts for development purposes.
+
+
+## System Testing
+
+To test integrated portions of the PlayOS system, there are several options/levels available:
+
+- Running a single system partition with QEMU (fast, partial, isolated)
+- Running a full system inside a virtual machine such as VirtualBox (slow, simulated full, isolated)
+- Running a single system partition from a USB stick on a physical machine (medium fast, partial, isolated)
+- Running a full system on a physical machine (slow, full, isolated)
+
+### QEMU VM
+
+Most changes to system configuration and/or the controller can be tested in a virtual machine.
+To create and run a VM, run:
+
+```bash
 ./build vm
+./result/bin/run-in-vm
 ```
 
 In order to get the vm system journal, look at the output of `run-in-vm`
 for a command starting with `socat`.
 
-See the output of `run-in-vm --help` for more information.
+See the output of `./result/bin/run-in-vm --help` for more information.
 
 #### Guest networking
 
-The default user-mode network stack is used to create a virtual Ethernet connection with bridged Internet access for the guest. If you find that the guest has a dysfunctional Internet connection, check your host's firewall settings. If using ConnMan, restart ConnMan service and try again.
+The default user-mode network stack is used to create a virtual Ethernet connection with bridged Internet access for the guest. If you find that the guest has a dysfunctional Internet connection, check your host's firewall settings. If using ConnMan on the host, restart the ConnMan service and try again.
+
+### VirtualBox VM
+
+PlayOS can also be tested on a VM like VirtualBox, which can simulate a system more fully, including the installer, Grub and A/B partitions. Guidance for setting this up can be found [here](./docs/arch/Readme.org#installation-on-virtualbox).
+
+### Testing on PlayOS hardware
+
+Changes such as NixOS upgrades, or to anything else that directly interacts with system hardware may necessitate testing on physical hardware. This can be done by booting from a live system or performing a complete installation.
+
+To build only a live system:
+
+```bash
+nix-build --arg buildInstaller false --arg buildBundle false --arg buildDisk false
+```
+
+To build only an installer:
+
+```bash
+nix-build --arg buildLive false --arg buildBundle false --arg buildDisk false
+```
+
+Flash the ISO in `./result/` to a USB stick and boot or install PlayOS.
+
+Building a complete system takes time, so it is a good idea to test at the component or QEMU VM level first, where possible.
 
-## Testing
+### Automated Testing
 
 Subcomponent tests using the [NixOS test framework](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests) may be added to `test/integration`.
 

build

@@ -25,12 +25,20 @@ if [ "$TARGET" == "vm" ]; then
     --arg buildLive false \
     --arg buildDisk false)
 
-  echo
-  echo "Run ./result/bin/run-in-vm to start a VM."
-  echo
-  echo "- unfocus: ctrl-alt-g"
-  echo "- quit: ctrl-alt-q"
-  echo "- tty: ctrl-alt-2, sendkey ctrl-alt-f1, ctrl-alt-1"
+echo -e "
+Run ./result/bin/run-in-vm to start a VM.
+
+QEMU Shortcuts:
+- Grab/release cursor: ctrl-alt-g
+- Quit: ctrl-alt-q
+
+PlayOS shortcuts:
+- Toggle controller: ctrl-shift-f12
+
+You can switch virtual consoles in the guest via QEMU monitor (ctrl-alt-2), sending a key combination via 'sendkey <key-comb>, and returning to QEMU display (ctrl-alt-1).
+- Status console: ctrl-alt-f8
+- Graphical system: ctrl-alt-f7
+"
 
 elif [ "$TARGET" == "develop" ]; then
 

controller/Readme.md

@@ -14,9 +14,34 @@ PlayOS controller is an OCaml application that manages various system tasks for
 - `server/`: main application code
 - `bin/`: binaries to start a dev server
 
+## Prerequisites
+
+Since the controller uses `Connman` for managing networks, it must be configured on your host if you want to run the controller directly.
+
+You should be able to build and run the controller on any Linux system, using the Nix package manager.
+
+If you are on NixOS, a minimal setup can be achieved as follows (remember to fill in `<your-host-name>`):
+
+```nix
+{ pkgs, config, ... }:
+{
+  networking = {
+    hostName = <your-hostname>;
+    wireless.enable = true;
+    networkmanager.enable = false;
+  };
+
+  services.connman = {
+    enable = true;
+    networkInterfaceBlacklist = [ "vboxnet" "zt" ];
+  };
+}
+```
+
+Note the `networkmanager.enable = false` and check for any conflicting existing configuration.
+
 ## Quick start
 
-Prerequisites: `connman` must be running on your system.
 
 Run `nix-shell` to create a suitable development environment.