# Saleculator POS

Saleculator is an offline-first Java desktop POS that is known to run on Linux and Raspberry Pi class devices. This repository still uses the original NetBeans/Ant project layout; the scripts in `scripts/` provide a stable command-line path for rebuilding and launching it without the IDE.

## Requirements

- JDK 17 or newer. The project currently compiles with `source=17` and `target=17`.
- Apache Ant 1.10 or newer.
- A local MySQL database with database name `SALECULATOR`.
- POS device native libraries/drivers as needed for the deployment: printers, serial ports, scales, cash drawer, scanner, and Raspberry Pi GPIO hardware.

On Debian/Raspberry Pi OS, the build tools are typically:

```sh
sudo apt-get update
sudo apt-get install ant openjdk-17-jdk
```

Use Java 17 as the standard runtime for release testing and customer deployments.

## Build

```sh
scripts/build.sh
```

On Windows:

```bat
scripts\build.bat
```

The build output is:

```text
dist/Saleculator.jar
```

## Vendor Runtime ZIP

Customer releases are published at `https://www.saleculator.com/releases/` with version-specific release notes. Customers should normally download the Windows installer for their version and install/setup Saleculator themselves. Hardware vendors and technicians can still use the runtime ZIP instead of the full source tree when they need manual Windows, Linux, or Raspberry Pi deployment.

The ZIP contains the same built JAR and `lib` directory for Windows, Linux, and Raspberry Pi, plus deployment scripts, release notes, and a sample config.

On Linux/Raspberry Pi:

```sh
scripts/package-release.sh
```

On Windows:

```bat
scripts\package-release.bat
```

The artifact is written under `release/` as:

```text
saleculator-<version>-runtime.zip
```

After unpacking the ZIP:

- Windows technicians run `scripts\run.bat`.
- Linux technicians run `chmod +x scripts/*.sh` once, then `scripts/run.sh`.
- First-time customer or AI-assisted setup starts with `scripts\setup-saleculator.bat` on Windows or `scripts/setup-saleculator.sh` on Linux/Raspberry Pi.
- If Saleculator starts before MySQL is ready, use **Database Settings** from the database setup screen, then choose **Use Local MySQL**, **Use Network MySQL**, or **Test Connection**.
- Minimal Debian/Raspberry Pi appliance installs use `sudo sh scripts/install-linux-appliance.sh`.
- The sample config is `config/Saleculator.properties.sample`; copy or adapt it to the deployed machine's real `Saleculator.properties`.
- Vendor-only instructions are in `README-VENDOR.md`.
- AI/customer installation instructions are in `AI-INSTALLATION-GUIDE.md`.
- Version release notes are in `RELEASE-NOTES.md`.
- Release build and publish steps are in `RELEASE-CHECKLIST.md`.
- Public release page source content is in `PUBLIC-RELEASE-PAGE.md`.
- Support collection is available with `scripts\support-info.bat` or `scripts/support-info.sh`.
- Release metadata is written to `release-info.properties`.

## Run

From the repository or install root:

```sh
scripts/run.sh
```

On Windows:

```bat
scripts\run.bat
```

For guided first-time setup:

```bat
scripts\setup-saleculator.bat
```

On Linux/Raspberry Pi:

```sh
scripts/setup-saleculator.sh
```

The assistant covers standalone/main POS setup, network-client setup, preflight, launch, and support-info collection. A new customer can request the built-in 30 day trial from the activation screen using the **START TRIAL** button.

To use a specific configuration file:

```sh
scripts/run.sh /path/to/Saleculator.properties
```

If no config file is passed, Saleculator uses the standard user-home configuration file:

```text
~/Saleculator.properties
```

## Preflight Check

Run the preflight check before launching on a field machine:

```sh
scripts/preflight.sh
```

On Windows:

```bat
scripts\preflight.bat
```

To check a specific configuration file:

```sh
scripts/preflight.sh /path/to/Saleculator.properties
```

The preflight check verifies Java, Ant availability, the generated application JAR, key libraries, database configuration, MySQL reachability when possible, and Linux/Raspberry Pi permissions commonly needed for serial printers, USB printers, and GPIO.

## Configuration

Do not commit shop credentials or machine-specific settings. Runtime values such as database passwords, WhatsApp tokens, SMTP passwords, remote access keys, printer names, and scale IP addresses should live in the deployed machine's `Saleculator.properties`.

The tracked default configuration under `src-pos/com/posics/pos/Saleculator.properties` is intentionally sanitized and should not contain live credentials.

WhatsApp template examples for Meta/Chazt approval and Saleculator event scripts are in `src-pos/com/posics/pos/templates/WhatsApp.MetaTemplates.txt`.

## Linux And Raspberry Pi Notes

- Launch the app from the install root so the scripts can resolve `lib/*`.
- Keep `dist/Saleculator.jar` and the root `lib/` directory together.
- Serial, USB, printer, and GPIO access may require Linux group permissions such as `dialout`, `lp`, or `gpio`, depending on the device.
- Some legacy serial integrations may need native RXTX libraries installed on the target OS.
- For kiosk counters, configure OS boot to start only Saleculator after the database and hardware services are ready.

## Minimal Debian Appliance Mode

Saleculator field devices are expected to behave like appliances: the OS boots, shows the Saleculator/bootstrap loader, and opens directly to the Saleculator PIN login screen with no desktop options exposed.

Install the built application files:

```sh
sudo scripts/install-linux-appliance.sh
```

After editing `/etc/saleculator/Saleculator.properties`, enable kiosk boot:

```sh
sudo scripts/install-linux-appliance.sh --enable-kiosk
```

The kiosk service template is [deploy/linux/saleculator-kiosk.service](deploy/linux/saleculator-kiosk.service). It starts X on tty1 and runs [scripts/kiosk-session.sh](scripts/kiosk-session.sh), which disables screen blanking, hides the pointer when possible, and launches Saleculator.

Expected minimal Debian/Raspberry Pi packages:

```sh
sudo apt-get install openjdk-17-jre xserver-xorg xinit unclutter mysql-client
```

Use Java 17 or newer as the release runtime.

## Release Checklist

Before publishing a release to saleculator.com:

- Build with `scripts/build.sh` or `scripts\build.bat`.
- Update `RELEASE-NOTES.md` for the version.
- Complete `RELEASE-CHECKLIST.md`.
- Confirm `dist/Saleculator.jar` exists.
- Build the customer Windows installer when Inno Setup is available.
- Publish the installer, runtime ZIP, checksum information, and release notes at `https://www.saleculator.com/releases/`.
- Run `scripts/preflight.sh` or `scripts\preflight.bat`.
- Confirm no live credentials are present in tracked files.
- Configure the local database and `~/Saleculator.properties`.
- On appliance devices, verify `saleculator-kiosk.service` boots to the PIN login screen on tty1 without exposing the desktop.
- Verify printer, barcode scanner, cash drawer, and scale behavior on the actual target hardware.
- Built-in Administrator, Manager, and Cashier seed PINs are bootstrap credentials only; the app forces a PIN change when one of those known defaults is used.
- If the Webadmin user is needed, assign a password deliberately before enabling remote/Webin access.
