# MX240a Linux CLI v0.2.1.1 - Detailed Usage Guide

This guide covers installation, configuration, service management,
handheld registration, AIM/OSCAR login, messaging, chat rooms, multiple
handhelds, upgrades, and troubleshooting for the MX240a Linux CLI Debian
package.

## 1. Install the Debian package

Copy the compiled Debian package to your Debian 13 server. The current
package name is:

``` text
mx240a-cli_0.2.1-2_amd64.deb
```

Install it:

``` bash
cd ~
sudo apt install ./mx240a-cli_0.2.1-2_amd64.deb
```

The package installs the important components:

``` text
/usr/bin/mx240a-cli
/usr/sbin/mx240a-cli-control
/etc/mx240a/mx240a.conf
/usr/lib/systemd/system/mx240a-cli.service
/usr/lib/udev/rules.d/99-mx240a.rules
```

Normally, do not run `/usr/bin/mx240a-cli` manually. It is designed to
run continuously as a systemd service.

## 2. Configure the OSCAR server

Open the configuration file:

``` bash
sudo nano /etc/mx240a/mx240a.conf
```

Default example:

``` ini
[oscar]
server=retro-chat.com
port=5190
```

To use another compatible OSCAR server:

``` ini
[oscar]
server=logon.chat
port=5190
```

Save in Nano with `Ctrl+O`, press `Enter`, then `Ctrl+X`.

The handheld supplies its own screen name and password. Do not put AIM
usernames or passwords in this file.

## 3. Connect the MX240a base

Plug the MX240a base into USB.

Check that Linux sees it:

``` bash
lsusb
```

You can also inspect HID devices:

``` bash
ls -l /dev/hidraw*
```

The Debian package installs the udev rule needed by the bridge. If the
base was already connected while installing the package, unplug it and
plug it back in once.

## 4. Start and enable the service

Start the service and enable it at boot:

``` bash
sudo systemctl enable --now mx240a-cli
```

Check status:

``` bash
systemctl status mx240a-cli
```

You want:

``` text
Active: active (running)
```

Quick active check:

``` bash
systemctl is-active mx240a-cli
```

Expected:

``` text
active
```

Check whether it starts automatically:

``` bash
systemctl is-enabled mx240a-cli
```

Expected:

``` text
enabled
```

## 5. Watch the live MX240a log

The most useful diagnostic command is:

``` bash
sudo journalctl -u mx240a-cli -f
```

Leave this running in a terminal while registering and testing
handhelds.

Press `Ctrl+C` to stop watching the log. This exits journalctl only; it
does not stop the MX240a service.

## 6. Register the first handheld

Registration is closed by default.

Check the registration state:

``` bash
sudo mx240a-cli-control registration status
```

Expected:

``` text
MX240a registration CLOSED.
```

Open registration for the default 60 seconds:

``` bash
sudo mx240a-cli-control registration open
```

Expected:

``` text
MX240a registration OPEN for 60 seconds.
```

Now put the physical MX240a handheld into its normal registration mode.

In the live service log, you should see activity similar to:

``` text
REGISTRATION REQUEST id=... -> ACCEPTED (registration window open)
HANDSET 1 CONNECT ...
SESSION 1 CREATED
```

### Longer registration windows

Two minutes:

``` bash
sudo mx240a-cli-control registration open 120
```

Five minutes:

``` bash
sudo mx240a-cli-control registration open 300
```

The maximum manually selected registration window is 3600 seconds.

### Check remaining registration time

``` bash
sudo mx240a-cli-control registration status
```

Example:

``` text
MX240a registration OPEN (43 seconds remaining).
```

### Close registration early

``` bash
sudo mx240a-cli-control registration close
```

Closing registration does not disconnect already registered or active
handhelds.

## 7. Sign into AIM/OSCAR

After registration, use the handheld itself to enter the AIM/OSCAR
screen name and password.

The connection flow is:

``` text
MX240a Handheld
       |
       v
MX240a Base
       |
       v
mx240a-cli
       |
       v
Configured OSCAR Server
```

Nothing needs to be entered into Linux for individual user credentials.

Watch the log:

``` bash
sudo journalctl -u mx240a-cli -f
```

A successful login should look generally like:

``` text
HANDSET 1 CONNECT ...
SESSION 1 CREATED
OSCAR LOGIN handset=1 user=ke5eua server=retro-chat.com:5190
OSCAR[1] Connected to auth server...
OSCAR[1] Authentication accepted...
OSCAR[1] Connected to BOS...
OSCAR LOGIN OK handset=1 user=ke5eua
```

Then the buddy list should begin arriving:

``` text
BUDDY handset=1 id=1 ...
BUDDY handset=1 id=2 ...
BUDDY handset=1 id=3 ...
```

If the username or password is incorrect, the daemon resets that
handset's login state so the user can try again without restarting the
service.

## 8. Instant messages

Messages are sent from the handheld, not from Linux commands.

Select a buddy on the MX240a and send normally.

Outgoing activity may appear as:

``` text
IM -> OSCAR handset=1 target=mike text=hello
```

Incoming activity may appear as:

``` text
IM <- OSCAR handset=1 from=mike text=hey
```

The daemon routes the incoming message to the physical handset that owns
that OSCAR session.

## 9. Private chat rooms

Each handheld can independently use its normal:

``` text
Chat1
Chat2
Chat3
```

The bridge supports handheld-created rooms:

``` text
Handheld creates chat
        |
        v
OSCAR room created
        |
        v
Invitations sent
        |
        v
Other AIM clients join
```

It also supports rooms created by another AIM client:

``` text
AIM user creates chat
        |
        v
Invites MX240a user
        |
        v
mx240a-cli receives invitation
        |
        v
Joins existing OSCAR room
        |
        v
Chat appears on handheld
```

The daemon suppresses OSCAR reflections of the handheld user's own room
messages so sent text does not appear twice.

## 10. Multiple handhelds

One `mx240a-cli` service controls the base. Do not start a separate
daemon for every handset.

The software supports up to seven independent handset sessions:

``` text
MX240a Base
 |
 +-- Handset 1 -> OSCAR account 1
 +-- Handset 2 -> OSCAR account 2
 +-- Handset 3 -> OSCAR account 3
 +-- Handset 4 -> OSCAR account 4
 +-- Handset 5 -> OSCAR account 5
 +-- Handset 6 -> OSCAR account 6
 +-- Handset 7 -> OSCAR account 7
```

Each handset maintains its own:

-   OSCAR connection
-   screen name and login state
-   buddy list and buddy IDs
-   active IM routing
-   presence
-   Chat1, Chat2, and Chat3 state
-   chat invitations and messages

To add another handheld:

``` bash
sudo mx240a-cli-control registration open
```

Then register the next physical unit and sign into its OSCAR account
from that handheld.

## 11. Service administration

Check status:

``` bash
systemctl status mx240a-cli
```

Start:

``` bash
sudo systemctl start mx240a-cli
```

Stop:

``` bash
sudo systemctl stop mx240a-cli
```

Restart:

``` bash
sudo systemctl restart mx240a-cli
```

Enable at boot:

``` bash
sudo systemctl enable mx240a-cli
```

Disable automatic startup:

``` bash
sudo systemctl disable mx240a-cli
```

Enable and start together:

``` bash
sudo systemctl enable --now mx240a-cli
```

## 12. Change OSCAR servers

Edit:

``` bash
sudo nano /etc/mx240a/mx240a.conf
```

Example:

``` ini
[oscar]
server=some-other-server.example
port=5190
```

Restart the daemon after changing the configuration:

``` bash
sudo systemctl restart mx240a-cli
```

Then watch:

``` bash
sudo journalctl -u mx240a-cli -f
```

## 13. Server reboot behavior

Registered handhelds normally do not need to be registered again after a
Linux reboot.

Expected flow:

``` text
Debian boots
    |
    v
systemd starts mx240a-cli
    |
    v
MX240a USB base opens
    |
    v
base recovery polling
    |
    v
registered handhelds reconnect
    |
    v
individual OSCAR sessions reconnect
```

The temporary registration-open window does not survive reboot.
Registration returns to CLOSED automatically.

## 14. Troubleshooting

### Service status

``` bash
systemctl status mx240a-cli
```

### Last 100 log lines

``` bash
sudo journalctl -u mx240a-cli --no-pager -n 100
```

### Logs from the current boot

``` bash
sudo journalctl -b -u mx240a-cli
```

### Live logs

``` bash
sudo journalctl -u mx240a-cli -f
```

### Verify the executable

``` bash
ls -lh /usr/bin/mx240a-cli
/usr/bin/mx240a-cli --version
```

For this release, the application should report version `0.2.1.1`.

### Verify the service definition

``` bash
systemctl cat mx240a-cli
```

The important line should be:

``` ini
ExecStart=/usr/bin/mx240a-cli
```

### Verify configuration

``` bash
cat /etc/mx240a/mx240a.conf
```

### Verify USB detection

``` bash
lsusb
ls -l /dev/hidraw*
```

## 15. Upgrade to a newer Debian package

When a newer package is available, install it over the existing version:

``` bash
sudo apt install ./mx240a-cli_NEW-VERSION_amd64.deb
```

Then restart:

``` bash
sudo systemctl restart mx240a-cli
```

Check:

``` bash
systemctl status mx240a-cli
/usr/bin/mx240a-cli --version
```

The OSCAR configuration under `/etc/mx240a/mx240a.conf` is packaged as
configuration data so normal Debian configuration-file upgrade handling
applies.

## Quick Reference

``` bash
# Check daemon
systemctl status mx240a-cli

# Watch live activity
sudo journalctl -u mx240a-cli -f

# Open registration for 60 seconds
sudo mx240a-cli-control registration open

# Open registration for 120 seconds
sudo mx240a-cli-control registration open 120

# Check registration window
sudo mx240a-cli-control registration status

# Close registration
sudo mx240a-cli-control registration close

# Restart daemon
sudo systemctl restart mx240a-cli

# Edit OSCAR server
sudo nano /etc/mx240a/mx240a.conf

# Enable and start at boot
sudo systemctl enable --now mx240a-cli
```

The normal workflow is:

**Install the `.deb` -\> configure the OSCAR server -\> connect the
MX240a base -\> enable/start the service -\> open registration -\>
register a handheld -\> sign into AIM/OSCAR from the handheld -\> use
the handheld normally.**