README: Overhaul readme

README.md

@@ -33,34 +33,70 @@ with `-Ggtk_doc=true`
     ninja -C _build
     ninja -C _build calls-doc
 
-## Running
+## Running from the source tree
-Calls has a variety of backends.  The default backend is "mm", which
-utilises ModemManager.  To choose a different backend, use the -p
-command-line option.  For example, to run with the dummy backend and
-some useful debugging output:
 
-    export G_MESSAGES_DEBUG=all
+The most comfortable way to run from the source tree is by using the provided
-    /usr/local/bin/gnome-calls -p dummy
+run script which sets up the environment for you:
 
-If using ModemManager, Calls will wait for ModemManager to appear on
+    _build/run
-D-Bus and then wait for usable modems to appear.  The UI will be
-inactive and display a status message until a usable modem appears.
 
-### Running from the build directory
+## Debugging
-You can run calls without having to install it by executing the run script in
-the build folder, i.e. `_build/run`. This script will setup the needed environment
-and start Calls.
 
-### Call provider backends
+When trying to understand issues in applications debugging logs are invaluable
-Call provider backends are compiled as plugins and can be loaded and unloaded at runtime
+tools. Enable debug logging by invoking Calls with `-vvv` arguments.
-using the `-p` command line flag, followed by the plugin name.
 
-Setting the `CALLS_PLUGIN_DIR` environment variable will include the specified
+In the case of crashes you should provide a backtrace where possible.
-directory in the plugin search path. F.e.
+If your system is using systemd you may find
+[this guide](https://developer.puri.sm/Librem5/Development_Environment/Boards/Troubleshooting/Debugging.html)
+useful.
 
-    export CALLS_PLUGIN_DIR=_build/plugins/
+## Call provider backends
-    /usr/local/bin/gnome-calls -p dummy
 
+Calls uses libpeas to support runtime loadable plugins which we call "providers".
+Calls currently ships four different plugins:
+
+- mm: The ModemManager plugin used for cellular modems
+- sip: The SIP plugin for VoIP
+- dummy: A dummy plugin
+- ofono: The oFono plugin used for cellular modems (not in active development)
+
+By default Calls will load the `mm` and `sip` plugins.
+If you want to load other plugins you may specify the `-p <PLUGIN>` argument
+(you can pass multiple `-p` arguments) when invoking calls, f.e.
+
+    _build/run -p sip -p dummy
+    /usr/bin/gnome-calls -p mm
+
+Every plugins uses the following concepts:
+- CallsProvider: The principal abstraction of a library allowing to place and
+receive calls.
+- CallsOrigin: Originates calls. Represents a single modem or VoIP account.
+- CallsCall: A call.
+
+There is a one to many relation between provider and origins and between origins
+and calls. F.e. you have one SIP provider managing multiple SIP accounts (=origins)
+each of which can have multiple active calls (not yet implemented).
+
+### ModemManager
+
+This is the default backend for cellular calls. It uses `libmm-glib` to
+talk to ModemManager over DBus. It currently only supports one modem and
+one active call at a time.
+
+
+### SIP
+
+This plugin uses the libsofia-sip library for SIP signalling and
+GStreamer for media handling. It supports multiple SIP accounts and
+currently one active call at a time (subject to change).
+
+### Dummy
+
+This plugin is mostly useful for development purposes and work on the UI
+as it allows simulating both outgoing and incoming calls. To trigger an
+incoming call you should send a `USR1` signal to the calls process:
+
+    kill -SIGUSR1 $(pidof gnome-calls)
 
 ### oFono