Document integration of nerd

docs/configure.md

@@ -1,11 +0,0 @@
-# Configure FieldPOC
-
-```
-services.fieldpoc = {
-  enable = true;
-  ommIp = "10.42.132.2";
-  ommUser = "omm";
-  ommPasswordPath = pkgs.writeText "ommpassword" "rfpL43wlan";
-  sipsecretPath = pkgs.writeText "sipsecret" "c1e0aba8e0fc3ed3";
-};
-```

docs/extension/nerd.md

@@ -0,0 +1,33 @@
+# Nerd web interface
+
+Nerd is a web interface for managing extensions.
+
+Source code: <https://github.com/dect-e/nerd/>
+
+## Sync extensions to FieldPOC
+
+Nerd has an HTTP endpoint generation a FieldPOC compatible extensions file.
+
+You can adopt the follwing NixOS configuration snipped.
+It downloads the JSON file, copies it to the location FieldPOC expects the extensions and reload FieldPOC.
+
+```
+systemd.services.fieldpoc-nerd = {
+wantedBy = ["multi-user.target"];
+startAt = "*-*-* *:*:00";
+script = let
+  reloadScript = pkgs.writeText "reload" ''
+    spawn ${pkgs.inetutils}/bin/telnet localhost 9437
+    expect "> "
+    send "reload\n"
+    expect "> "
+    send "exit\n"
+    expect "disconnecting"
+  '';
+in ''
+  ${pkgs.curl}/bin/curl https://nerd.example.com/export.json\?event=1 > /etc/fieldpoc/extensions.json
+
+  ${pkgs.expect}/bin/expect ${reloadScript}
+'';
+};
+```

docs/index.md

@@ -1,3 +1,5 @@
 # FieldPOC
 
 A simple to use, good enough phone system for medium sized DECT networks.
+
+The source code can be found at: <https://git.clerie.de/clerie/fieldpoc/>

docs/install/configure.md

@@ -0,0 +1,21 @@
+# Configure FieldPOC
+
+To enable FieldPOC on the system just add this config.
+
+```
+services.fieldpoc = {
+  enable = true;
+  ommIp = "10.42.132.2";
+  ommUser = "omm";
+  ommPasswordPath = "/var/src/secrets/fieldpoc/ommpassword";
+  sipsecretPath = "/var/src/secrets/fieldpoc/sipsecret";
+};
+```
+
+- `ommIp` is the IP address of your OMM.
+- `ommUser` is the user account that FieldPOC uses to access the OMM. You usually want to set this to `omm`.
+- `ommPasswordPath` is the path to a file containing the password for the OMM user. This password is configured when [setting up the OMM](omm.md#login-credentials).
+
+- `sipsecretPath` is a path to a file containing a 16 characters hex string. FieldPOC is generating internal SIP accounts for each DECT user. So nobody can hijack these accounts, this secret is used as a seed for generating passwords for these accounts.
+
+When enabling the FieldPOC module a correctly configured Yate service is added to your system.

docs/operation/claim-dect-extension.md

@@ -0,0 +1,11 @@
+# Claim DECT extension
+
+Get a DECT phone an connect it to a new DECT base station.
+It will require an authentication code.
+This code got specified while [setting up the OMM](../install/omm.md#dect-devices-subscription).
+
+Wait for the base station registration succeed.
+
+After the base station registration wait a bit more to get a temporary number assigned.
+Then call `DECT claim token base` + `dect_claim_token`.
+The call should succeed and the DECT phone got the claimed token assigned.

docs/operation/troubleshooting.md

@@ -0,0 +1,8 @@
+# Troubleshooting
+
+## Registering DECT phone to base station does not work anymore
+
+Make sure DECT `Subscription` is still set to `Subscription`.
+Sometimes this changes back to `Off` by itself.
+
+See [OMM setup](../install/omm.md#dect-devices-subscription)

docs/reference/command-line-options.md

@@ -0,0 +1,21 @@
+# Command line options
+
+## Config file path
+
+`-c`, `--config <path>`
+
+Specifies the path to [FieldPOC configuration file](configuration.md).
+Of ommitted it looks for a file called `fieldpoc_config.json` in the current working directory.
+
+## Init
+
+`--init`
+
+Set up database. Run only once.
+
+## Debug
+
+`--debug`
+
+Sets log level to debug.
+Logs to stdout.

docs/reference/configuration.md

@@ -0,0 +1,60 @@
+# FieldPOC configuration
+
+`fieldpoc.json` is the main configuration file for FieldPOC. It is in JSON format.
+
+## Example config
+
+```
+{
+  "extensions": {
+    "file": "fieldpoc_extensions.json"
+  },
+  "controller": {
+    "host": "127.0.0.1",
+    "port": 9437
+  },
+  "dect": {
+    "host": "10.222.222.11",
+    "username": "omm",
+    "password": "xxx",
+    "sipsecret": "51df84aace052b0e75b8c1da5a6da9e2"
+  },
+  "yate": {
+    "host": "127.0.0.1",
+    "port": 5039
+  },
+  "database": {
+    "hostname": "127.0.0.1",
+    "username": "fieldpoc",
+    "password": "fieldpoc",
+    "database": "fieldpoc"
+  }
+}
+```
+
+## Controller
+
+Configuration for the FieldPOC controller.
+
+- `host`: IP address to listen on for controller socket.
+- `port`: Port to listen on for controller socket.
+
+## DECT
+
+- `host`: IP address of the OMM.
+- `username`: Username of OMM account.
+- `password`: Password of OMM account.
+- `sipsecret`: Secret used to seed DECT SIP account passwords.
+
+## Yate
+
+- `host`: IP address Yate control socket is reachable.
+- `port`: Port yate control socket is reachable.
+
+## Database
+
+- `hostname`: IP address PostgreSQL database is reachable.
+- `username`: Username of the database user.
+- `password`: Password of the database user.
+- `database`: Database name for FieldPOC.
+

docs/reference/controller.md

@@ -0,0 +1,58 @@
+# FieldPOC controller
+
+The FieldPOC controller is an interactive console to help managing the current state of the FieldPOC system.
+
+Connect to it via the IP address von port set in the [FieldPOC configuration](configuration.md) with `telnet`.
+
+## Commands
+
+### Help
+
+`help`
+
+Show help info.
+
+### Show handlers
+
+`handlers`
+
+Show currently running handlers
+
+### Reconfigure all components
+
+`sync`
+
+Notify all parts of FieldPOC to check configuration of connected components and update it.
+
+### Show queue stats
+
+`queues`
+
+### Reload configuration
+
+`reload`
+
+Read [FieldPOC configuration](configuration.md) file and apply it.
+
+### Bind extension to DECT device
+
+`claim <ext> <token>`
+
+- `ext` is the current extension number of the DECT device.
+- `token` is the `dect_claim_token` of the extension that should get applied.
+
+This works because newly connected DECT phones get a temporary number assigned.
+This temporary number is usually the current number.
+But it is possible to use any extension, so the extension for a device can be changed any time.
+
+### Disconnect
+
+`exit`
+
+Disconnect telnet session.
+
+### Stop controller
+
+`stop`
+
+Shutdown the controller, but FieldPOC continues running.

docs/reference/extensions.md

@@ -0,0 +1,100 @@
+# Extensions data
+
+`extensions.json` contains all extension a FieldPOC instance provides.
+
+## Example
+
+```
+{
+  "extensions": {
+    "2574": {
+      "name": "clerie",
+      "type": "dect",
+      "trunk": false,
+      "dialout_allowed": true,
+      "dect_claim_token": "2574"
+    },
+    "5375": {
+      "name": "n0emis",
+      "type": "callgroup",
+      "dialout_allowed": true,
+      "trunk": false,
+      "callgroup_members": [
+        "5376",
+        "5377",
+        "5379"
+      ]
+    },
+    "5376": {
+      "name": "n0emis SIP",
+      "type": "sip",
+      "dialout_allowed": true,
+      "trunk": false,
+      "outgoing_extension": "5375",
+      "sip_password": "wieK5xal"
+    },
+    "5377": {
+      "name": "n0emis DECT",
+      "type": "dect",
+      "dialout_allowed": true,
+      "trunk": false,
+      "outgoing_extension": "5375",
+      "dect_ipei": "10345 0136625 3"
+    },
+    "9998": {
+      "name": "Temporary Numbers",
+      "trunk": false,
+      "dialout_allowed": true,
+      "type": "temp"
+    },
+    "9997": {
+      "name": "DECT Claim Extensions",
+      "type": "static",
+      "dialout_allowed": false,
+      "trunk": true,
+      "static_target": "external/nodata//run/current-system/sw/bin/dect_claim"
+    }
+  }
+}
+
+```
+
+## Extensions definition
+
+The key for an extension is always the number of the extension.
+
+Following keys are required:
+
+- `name`: Description of the extension.
+- `type`: Type of the extension.
+
+## Extension types
+
+Based on the type of the extension more options are required.
+
+### SIP extension
+
+- `type`: `sip`
+- `sip_password`: Plain text password for the SIP account.
+
+### DECT extension
+
+- `type`: `dect`
+- `dect_claim_token`: Phone number part used to connect a DECT phone to this extension.
+- `dect_ipei`: IPEI of the DECT phone this extension should be connected to.
+
+`dect_claim_token` and `dect_ipei` are mutally exclusive.
+
+### Static extension
+
+- `type`: `static`
+- `static_target`: Path to script that is executed on calling this extension.
+
+### Temporary extension
+
+- `type`: `temp`
+
+### Callgroup extension
+
+- `type`: `callgroup`
+- `callgroup_members`: List of extension numbers that belong to this callgroup.

mkdocs.yml

@@ -6,10 +6,20 @@ theme:
 nav:
   - index.md
   - Installation:
-    - installation.md
-    - hardware.md
-    - nixos.md
-    - network.md
-    - configure.md
-    - rfp.md
-    - omm.md
+    - install/index.md
+    - install/hardware.md
+    - install/nixos.md
+    - install/network.md
+    - install/configure.md
+    - install/rfp.md
+    - install/omm.md
+  - Reference:
+    - reference/command-line-options.md
+    - reference/configuration.md
+    - reference/extensions.md
+    - reference/controller.md
+  - Operation:
+    - operation/claim-dect-extension.md
+    - operation/troubleshooting.md
+  - Extend:
+    - extension/nerd.md