# Astitvaams Print Helper

Lets Astitvaams print labels to a Brother label printer on your network.

A web page cannot talk to a printer directly — browsers do not allow it, on
purpose. This small program sits on your computer and does that one job.

---

## Install it

**Download for your computer, unzip, and double-click one file.**

| Your computer | Double-click | Needs admin? |
|---|---|---|
| Windows | `install.bat` | No |
| Mac | `install.sh` | No |
| Ubuntu / Linux | `install.sh` | Only if Python is missing |

**Windows installs Python for you** if it is not already there — you do not need
to find or install anything yourself.

A setup page then opens in your browser and asks three things:

1. **Your Astitvaams address** — the address you use to open Astitvaams
2. **Find my printer** — it looks on your network
3. **Print a test label** — a real label comes out, so you know it works

That is the whole install. It starts on its own every time the computer boots.

### On Mac or Linux, if double-click does nothing

Right-click `install.sh` → **Open With** → **Terminal**. Some systems open `.sh`
files in a text editor by default.

---

## Everyday use

Nothing. It runs quietly in the background. Open Astitvaams, go to Label Workspace,
and print.

To check it is alive, open <http://127.0.0.1:18726/ping> in a browser.
To change the Astitvaams address or reprint a test label, run the program again — the
same setup page opens.

---

## When printing does not work

**Nothing happens when you press print**

Almost always the Astitvaams address. The helper only accepts printing from the site
you told it about, and your browser blocks the rest before it ever reaches the
helper — which is why nothing happens and there is no error.

Run the helper again and check step 1 matches the address in your browser's
address bar exactly, including `https://`.

**"No printer found"**

- Is the printer switched on?
- Is it on the **same Wi-Fi** as this computer?
- Open the printer's own page in a browser — `http://<printer-ip>` — if that
  does not load, it is a network problem, not Astitvaams.

**A label comes out blank or the wrong size**

Check the roll. The printer's own page shows what it thinks is loaded, under
**Media Type**.

---

## For IT

| | |
|---|---|
| Port | `18726`, loopback only — never reachable from the network |
| Config | `~/.ams-print-helper/origins.txt` — one Astitvaams address per line |
| Printer | TCP port 9100, Brother raster |

Change the address without reinstalling by editing that file; it is re-read on
the next request, no restart needed. `AMS_HELPER_ORIGINS` (comma separated) and
`AMS_HELPER_PORT` override it for scripted rollouts, and `AMS_HELPER_SITE` sets
the address during an unattended install.

Autostart is per-user and needs no admin: Scheduled Task on Windows, LaunchAgent
on macOS, systemd user service on Linux.

Remove it with `Astitvaams-Print-Helper --uninstall`.

### Building the downloads

Each OS builds its own — PyInstaller cannot cross-compile:

```
pip install pyinstaller -r requirements.txt
python build.py
```

`.github/workflows/print-helper-release.yml` does all three on a tag push
(`print-helper-v*`) and attaches them to the release.