diff --git a/docs/reference/api/Makefile.am b/docs/reference/api/Makefile.am
index 69c11548..ea657d75 100644
--- a/docs/reference/api/Makefile.am
+++ b/docs/reference/api/Makefile.am
@@ -38,6 +38,7 @@ MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=mm
# Images to copy into HTML directory
HTML_IMAGES = \
+ ModemManager-states.png \
$(NULL)
content_files = \
@@ -75,6 +76,8 @@ EXTRA_DIST += \
mm-overview.xml \
mm-dbus-reference.xml \
version.xml.in \
+ ModemManager-states.dia \
+ ModemManager-states.png \
$(NULL)
CLEANFILES += \
diff --git a/docs/reference/api/ModemManager-states.dia b/docs/reference/api/ModemManager-states.dia
new file mode 100644
index 00000000..21e59479
--- /dev/null
+++ b/docs/reference/api/ModemManager-states.dia
@@ -0,0 +1,1210 @@
+
+
+
+
+
+
+
+
+
+
+
+
+ #Letter#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #LOCKED#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #INITIALIZED#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #DISABLING#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #SEARCHING#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #REGISTERED#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #DISCONNECTING#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #CONNECTING#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #CONNECTED#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #ENABLED#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #ENABLING#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #INITIALIZING#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #ENABLE#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #CONNECT#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #DISCONNECT#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #DISABLE#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ #INITIALIZE#
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/reference/api/ModemManager-states.png b/docs/reference/api/ModemManager-states.png
new file mode 100644
index 00000000..9ac1529a
Binary files /dev/null and b/docs/reference/api/ModemManager-states.png differ
diff --git a/docs/reference/api/mm-overview.xml b/docs/reference/api/mm-overview.xml
index 675acabe..95764795 100644
--- a/docs/reference/api/mm-overview.xml
+++ b/docs/reference/api/mm-overview.xml
@@ -1,56 +1,95 @@
]>
-
+
ModemManager Overview
-
- ModemManager
+
+ Introduction
ModemManager provides a unified high level API for communicating with
(mobile broadband) modems. While the basic commands are standardized,
the more advanced operations (like signal quality monitoring while
connected) varies a lot.
-
Using
ModemManager is a system daemon and is not meant to be used directly from
- the command line. However, since it provides DBus API, it is possible to use
- 'dbus-send' command to control it from the terminal. There's an example
- program (tests/mm-test.py) that demonstrates the basic API usage.
+ the command line. However, a command line client (mmcli) is provided, which
+ may be used to test the different functionality provided during plugin
+ development.
-
Implementation
ModemManager is a DBus system bus activated service (meaning it's started
automatically when a request arrives). It is written in C. The devices are
- queried from udev and automatically updated based on hardware events. There's
- a GInterface (MMModem) that defines the modem interface and any device specific
- implementation must implement it. There are two generic MMModem implementations
- to support the basic operations (one for GSM, one for CDMA,) which are common
- for all cards.
+ queried from udev and automatically updated based on hardware events. There are
+ DBus-interface specific GInterfaces, which should be implemented by any device
+ specific implementation. There is a generic MMBroadbandModem implementation that
+ provides a generic implementation of the most common operations in both GSM and
+ CDMA modems.
-
Plugins
Plugins are loaded on startup, and must implement the MMPlugin interface. It
consists of a couple of methods which tell the daemon whether the plugin
- supports a port and to create custom MMModem implementations. It most likely
+ supports a port and to create custom modem implementations. It most likely
makes sense to derive custom modem implementations from one of the generic
- classes and just add (or override) operations which are not standard. There's a
- fully working plugin in the plugins/ directory for Huawei cards that can be
- used as an example for writing new plugins. Writing new plugins is highly
- encouraged!
+ classes and just add (or override) operations which are not standard. Writing
+ new plugins is highly encouraged!
+
+
+ State machine
+
+ ModemManager implements support for each Modem by controlling their
+ behaviour following the steps given in the following state machine.
+
+
+ ModemManager states
+ ![]()
+
+
+ The state machine of a modem can be summarized in 5 main sequences:
+ initialization, enabling, connection, disconnection and disabling.
+
+
+
+
+
+