[peanut] Documentation

Author: teo

occ/README.md

@@ -20,8 +20,55 @@ or
 ```bash
 $ occlib/examples/dummy-process/occexample-dummy-process --control-port <some port>
 ```
+or
+```bash
+$ OCC_CONTROL_PORT=<some port> occlib/examples/dummy-process/occexample-dummy-process
+```
+
+The dummy process now waits for control commands.
+
+## Single process control with `peanut`
+
+`peanut` is the Process Execution And coNtrol UTility for OCClib-based O² processes. Its purpose
+is to be a debugging and development aid for non-FairMQ O² devices, where FairMQ's interactive
+controller is not available.
+
+In aliBuild it is part of the Control-core package.
+
+`peanut` can connect to a running OCClib-based process, query its status, drive its state machine
+and push runtime configuration data.
+
+Peanut is an interactive tool, the only information it picks up from its environment is the
+`OCC_CONTROL_PORT` variable, which is used to connect to a running OCClib-based process.
+
+```bash
+$ OCC_CONTROL_PORT=<some port> peanut
+```
+
+![Screenshot of peanut](peanut.png)
+
+Peanut commands are documented inline. Each transition is applied immediately and
+the state is updated in real time.
+
+Compared to the raw gRPC API, the following limitations apply:
+* It is not possible to perform a `GO_ERROR` transition, as this transition is only triggered from
+user code.
+* The `CONFIGURE` transition may be triggered both with and without runtime configuration data, which
+may or may not be suitable depending on user code. All other transitions send no payload.
+
+The last two commands are **not** transitions:
+* `Load configuration` allows the user to read in a JSON or YAML file containing sample
+configuration data that is then available to be pushed to the controlled process during a future
+`CONFIGURE` transition. On startup, there is no file loaded, so a `CONFIGURE` transition will push
+an empty payload. Once a runtime configuration file is loaded, its title bar reports `NOT PUSHED`
+until the next `CONFIGURE` transition, at which point it becomes `PUSHED`.
+* `Quit` disconnects from the controlled process and quits `peanut`, but it performs no transitions
+or other data exchange with the controlled process. A future instance of `peanut` may reattach itself
+to the same process and continue from there.
+
+## OCC API debugging with `grpcc`
 
-The dummy process now waits for control commands. We can send them manually with an interactive gRPC client
+We can send gRPC-based OCC commands manually with an interactive gRPC client
 like [`grpcc`](https://github.com/njpatel/grpcc):
 ```bash
 $ sudo yum install http-parser nodejs npm