From 5a2727c0f4ea72eec9e91a66f858640afc9ffe99 Mon Sep 17 00:00:00 2001 From: Evangelos Ribeiro Tzaras Date: Mon, 15 Nov 2021 12:16:51 +0100 Subject: [PATCH] README: Overhaul readme --- README.md | 78 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 57 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 154c56f..7310005 100644 --- a/README.md +++ b/README.md @@ -33,34 +33,70 @@ with `-Ggtk_doc=true` ninja -C _build ninja -C _build calls-doc -## Running -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: +## Running from the source tree - export G_MESSAGES_DEBUG=all - /usr/local/bin/gnome-calls -p dummy +The most comfortable way to run from the source tree is by using the provided +run script which sets up the environment for you: -If using ModemManager, Calls will wait for ModemManager to appear on -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. + _build/run -### Running from the build directory -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. +## Debugging -### Call provider backends -Call provider backends are compiled as plugins and can be loaded and unloaded at runtime -using the `-p` command line flag, followed by the plugin name. +When trying to understand issues in applications debugging logs are invaluable +tools. Enable debug logging by invoking Calls with `-vvv` arguments. -Setting the `CALLS_PLUGIN_DIR` environment variable will include the specified -directory in the plugin search path. F.e. +In the case of crashes you should provide a backtrace where possible. +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/ - /usr/local/bin/gnome-calls -p dummy +## Call provider backends +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 ` 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