====== Custom Applications in LinBPQ ======

When you connect to a BPQ32 Node, you may be offered custom applications as well as the standard commands:

<code>
ABNGDN:G6FJI} BBS CHAT HARS CONNECT BYE INFO NODES PORTS ROUTES USERS MHEARD
</code>

Here the first three commands are applications defined in the nodes configuration file, bpq32.cfg:

<code>
APPLICATION 1,BBS,,G6FJI-2,ABIBBS,254
APPLICATION 2,CHAT,,G6FJI-1,ABICHT,254
APPLICATION 3,HARS,C 1 HARS S
</code>

Applications 1 and 2, BBS and CHAT are standard features in BPQ32; Application 3 is simply a user shortcut: typing ''HARS'' is the same as typing ''C 1 HARS S''.

BPQ32 also has a facility to make a TCP connection to a port on the same machine, which allows you to create custom applications within your node.  This page describes setting up an application on a Linux system using systemd - I have not seen any documentation to make this work on Windows.

===== 'Hello World' Example Application =====
This example assumes you have a 'standard' BPQ32 installation running on Linux, with Port 1 using RF and Port 2 using Telnet.

==== BPQ32 Configuration ====
First we must add a CMDPORT line to the Telnet Port. The syntax is ''CMDPORT <TCP port 0> <TCP port 1> ...  <TCP port n>'', eg:

<code>
  CMDPORT 63001 63002
</code>

Then we add a Node APPLICATION which calls that port.  The options used here are:
  * Application number
  * Application name
  * Command to execute
  * User to connect as

<code>
  APPLICATION 5,HELLO-WORLD,C 2 HOST 0 S,G6FJI
</code>

The command syntax is ''C(onnect) <port> HOST <zero-based command port number> S''; the S at the end means return to the current session rather than disconnect completely.

==== Custom Application Configuration ====
Our 'Hello World' application is simply a bash script called as a systemd service.  Using your editor of choice, create a file 'hello-world.sh' containing this script:
<code>
#!/bin/bash
echo "Hello world"
</code>

Make the script executable and check you can run it:
<code>
martinr@UbuMini:~$ chmod +x hello-world.sh
martinr@UbuMini:~$ ./hello-world.sh
Hello world
</code>

Now we need to set up the systemd service to call the script.  This is in two parts - the socket and the service.  First create the socket part with ''sudo nano /lib/systemd/system/hw.socket''

<code>
[Unit]
Description=Hello World

[Socket]
ListenStream=63001
Accept=yes

[Install]
WantedBy=sockets.target
</code>

The bit that matters here is the port number in the ListenStream must match the CMDPORT you created in the BPQ configuration.

Then we need the matching service file: ''sudo nano /lib/systemd/system/hw@.service'' - note the @ in the name.

<code>
[Unit]
Description=Hello World Server

[Service]
ExecStart=/home/martinr/hello-world.sh
StandardInput=socket
</code>

Here the important parts are the script to run and the line telling it to take standard input from the socket - there won't be a keyboard connected to the service.

Reload the systemd configuration and start the service, then test it using netcat:

<code>
martinr@UbuMini:~$ sudo systemctl daemon-reload
martinr@UbuMini:~$ sudo systemctl start hw.socket
martinr@UbuMini:~$ nc localhost 63001
Hello world
</code>

To have the new service run on start up, run this command:
<code>
martinr@UbuMini:~$ sudo systemctl enable hw.socket
</code>

Finally restart your node and test:

<code>
ABNGDN:G6FJI} BBS CHAT HARS HELLO-WORLD CONNECT BYE INFO NODES PORTS ROUTES USERS MHEARD
HELLO-WORLD
Connected to HELLO-WORLD 
Hello world
Returned to Node ABNGDN:G6FJI
</code>




===== References =====
I found these links useful in getting this to work:

The official documentation uses inetd and doesn't really explain the significance of the port list in the CMDPORT line:\\
[[https://www.cantab.net/users/john.wiseman/Documents/LinBPQ%20Applications%20Interface.html]]

This presentation is quite helpful once you work out the typos and which bits are meant to be there:\\
[[https://www.prinmath.com/ham/talks/BPQ.pdf]]

These pages were useful for understanding the systemd services and testing them\\
[[https://www.linux.com/training-tutorials/writing-systemd-services-fun-and-profit/]]\\
[[https://mgdm.net/weblog/systemd-socket-activation/]]


Here is a completely separate write-up\\ 
[[https://labby.co.uk/linbpq-bpq32-linux-add-custom-application/]]

Another approach: https://github.com/bradbrownjr/bpq-apps