diff --git a/README.md b/README.md
index 07eed8e..c3540ab 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,96 @@
# Linux Fax Stack Setup (HylaFax & SIP)
-- ***This guide is WIP***
-- Ubuntu 20.04 LTS VM (VirtualBox, LXC?)
-- **TODO: Test on Debian / RockPi / RaspberryPi**
-- **TODO: Test on Eventphone Infra**
+Linux Fax Stack using Hylafax and t38modem.
-
+***THIS GUIDE IS WIP***
-## Setup t38modem
+This guide was created using information from the opalvoid wiki (http://wiki.opalvoip.org/index.php?n=Main.HomePage)
-- **TODO: Package t38modem with service files and config**
+## Softwarestack
-## Opal
+### ptlib
+(legacy) library for doing a little bit of everything.
-- http://wiki.opalvoip.org/index.php?n=Main.HomePage
+### Opal
+Voice codec used by e.g. mumble.
+
+### t38modem
+Emulates a serial modem from SIP connetion
+
+### Hylafax
+Enterprise grade software, managing physical and emulated modems.
+
+Has some problems: https://github.com/lexbailey/compilerfax/blob/main/hylafax_is_broken
+
+## Operating Systems
+Unfortunately this software stack uses a lot of legacy software. Because of this, this guide was only tested on specific software versions
+
+### Debian 12 Bookworm
+For Debian 12, we´ll only install dependencies which are hard requirements.
+For this guide we'll use ptlib 2.18.6 and opal 3.18.6.
+
+#### Installing Requirements
+First we'll need some packages
+```bash
+apt-get install build-essential git wget pkg-config libssl-dev libsrtp2-dev -y
+```
+#### Download sourcecode
+Versions:
+- libpt (2.18.6) https://sourceforge.net/projects/opalvoip/files/v3.18 Cygni/Stable 6/
+- opal (3.18.6) https://sourceforge.net/projects/opalvoip/files/v3.18 Cygni/Stable 6/
+- t38mdem (4.6.2) https://github.com/hehol/t38modem/releases/tag/4.6.2
+
+#### ptlib
+```bash
+./configure
+make
+make install
+```
+
+#### opal
+```bash
+./configure
+make -j5
+make runtest
+make install
+```
+
+#### t38modem
+If you are getting error about `-1` not being able to be casted to a `long unsigned int` due to `-Wnarrowing` inside `dle.cxx`, you can add `-Wno-narrowing` after the `CPPFLAGS` in the Makefile to disable this error
+
+```bash
+git clone https://github.com/hehol/t38modem
+cd t38modem
+make
+```
+
+If running the t38modem executable, you should run these commands
+```bash
+cp /usr/local/lib/libpt.so.2.18.6 /lib
+cp /usr/local/lib/libopal.so.3.18.6 /lib
+```
+
+To install t38modem run
+```bash
+cp ./t38modem /usr/local/bin
+```
+
+### Ubuntu 20.04 LTS
+Was tested on Ubuntu 20.04 LTS VM (VirtualBox, LXC?)
+
+You can relies heavily on http://wiki.opalvoip.org/index.php?n=Main.HomePage
+
+Versions:
+- libpt (2.18.6) https://sourceforge.net/projects/opalvoip/files/v3.18 Cygni/Stable 6/
+- opal (3.18.6) https://sourceforge.net/projects/opalvoip/files/v3.18 Cygni/Stable 6/
+- t38mdem (4.6.2) https://github.com/hehol/t38modem/releases/tag/4.6.2
+
+Follow http://wiki.opalvoip.org/index.php?n=Main.BuildingPTLibUnix and http://wiki.opalvoip.org/index.php?n=Main.HomePage **but**
- Don't use `libavformat-dev` -> Compile error in Opal
-- https://sourceforge.net/projects/opalvoip/files/
-- Version 3.18.6
-- **TODO: Test out other versions**
-- `.tar.bz2` files for *nix
+- Configure script needs `pkg-config` to be installed to find ptlib install
+- On SourceForge downloads `.tar.bz2` files for *nix
-### Build PTLib
+#### Build PTLib
- Version 2.18.6
- Dependency of Opal, bundled with Opal source code (SourceForge)
@@ -31,7 +101,7 @@
sudo apt install \
g++ git make autoconf libpcap-dev libexpat1-dev libssl-dev libsasl2-dev libldap2-dev \
unixodbc-dev liblua5.3-dev libv8-dev libncurses-dev libsdl2-dev \
- libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
+ libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev pkg-config
```
- PTLib will be installed in the `/usr/local` tree -> set `PKG_CONFIG_PATH` to be findable (compile time)
@@ -50,7 +120,7 @@ make
sudo make install
```
-### Build Opal
+#### Build Opal
- Version 3.18.6
- http://wiki.opalvoip.org/index.php?n=Main.BuildingOpalUnix
@@ -76,11 +146,11 @@ make
sudo make install
```
-## t38modem
+#### t38modem
- https://github.com/hehol/t38modem, Version 4.6.2
- - Could also use https://github.com/T38Modem/t38modem, not as maintained
-- If you are getting error about `-1` not being able to be casted to a `long unsigned int` due to `-Wnarrowing` inside `dle.cxx`, you can add `-Wno-narrowing` to the `CPPFLAGS` in the Makefile to disable this error
+ - https://github.com/T38Modem/t38modem could also be used, but seems to be not as maintained
+- If you are getting error about `-1` not being able to be casted to a `long unsigned int` due to `-Wnarrowing` inside `dle.cxx`, you can add `-Wno-narrowing` after the `CPPFLAGS` in the Makefile to disable this error
```bash
cd t38modem-x.y.z/
@@ -90,11 +160,18 @@ sudo cp ./t38modem /usr/local/bin
- t38modem can only find Opal if `LD_LIBRARY_PATH` and `PTLIBPLUGINDIR` are environment variables to the program
+
+
+## Configuring t38modem
### Init script
- To automatically start t38modem, you need to create Systemd services, as well as start and stop scripts
- script is adapted from https://web.archive.org/web/20111231021042/https://www.foriamroot.org/hylafax-6-0-debian-or-ubuntu-t38modem-1-0-asterisk-1-6/
-- `sudo mkdir -p /etc/t38modem/bin/`
+
+First we'll create the configuration directory under `/etc` using `sudo mkdir -p /etc/t38modem/bin/`.
+
+Then create a file named `/etc/t38modem/bin/run` using the following content.
+It will be the script to manage the current status of t38modem.
```bash
#!/bin/bash
@@ -139,16 +216,23 @@ esac
exit 0
```
+And then we'll have to make it executable like this.
+
```bash
sudo chmod +x /etc/t38modem/bin/run
```
+#### Quick script overview
+- Using that script, it is possible to `start` or `stop` the emulated modem.
- `-t` enables debugging
- More `t`'s is deeper debugging (e.g. `-tttt`)
- You can of course run the t38modem command without this init script
- If t38modem says it was able to create the virtual modem but `/dev/ttyT38-1` is not available, you do not have sufficient permissions
- Configuration is specified in `/etc/t38modem/config`
+### Create the configuration file
+Create a file using the following contents at `/etc/t38modem/config`.
+
```bash
# /etc/t38modem/config
T38MODEM_SIP_USERNAME="USERNAME"
@@ -156,18 +240,19 @@ T38MODEM_SIP_PASSWORD="PASSWORD"
T38MODEM_SIP_SERVER="voip.example.com"
```
-- Give only root access to the config
+You should give only root access to the config.
```bash
sudo chown root:root /etc/t38modem/config
sudo chmod 700 /etc/t38modem/config
```
-- You can now communicate with your modem `/dev/ttyT38-1` , just as if it was a real Hayes compatible modem (https://www.computerhope.com/atcom.htm)
+### Testing your setup
+- You can now communicate with your modem `/dev/ttyT38-1`, just as if it was a real Hayes compatible modem (https://www.computerhope.com/atcom.htm)
- Test using minicom, configure it to point to our modem. Each command is initiated by a Return
- Dial a number:
- Get the attention of the modem: `at` -> `OK`
- - Dial: `atd0123456789`
+ - Dial: `atd[NUMBER]`, replace '[NUMBER]' using the number, you want to call
- If all works correctly you should be able to answer the phone and hear a single beep
- Answer a call:
- Get the attention of the modem: `at` -> `OK`
@@ -180,6 +265,8 @@ sudo chmod 700 /etc/t38modem/config
- Test the command before running the init script!
### systemd service
+If you want to run a fax server, you can create a systemd service to let your emulated fax modem start automatically on system boot.
+To do this you have to copy paste the following into `/etc/systemd/system/t38modem.service`.
```toml
# /etc/systemd/system/t38modem.service
@@ -199,8 +286,7 @@ Restart=always
[Install]
WantedBy=multi-user.target
```
-
-- Enable the service:
+Enable and start the service using the following commands:
```bash
sudo systemctl daemon-reload
@@ -259,3 +345,8 @@ FaxMaster: $USER # replace with fax admin account
CountryCode: 1
AreaCode: 999
```
+
+## TODO
+- **TODO: Test on Debian / RockPi / RaspberryPi**
+- **TODO: Test on Eventphone Infra**
+- **TODO: Package t38modem with service files and config**