Sales & Dungeons (S&D)

A headless version of Sales & Dungeons (using LibUSB) is available as a Docker container. This allows you to run the service and access it via a web browser.

Manual Docker Run

1. Pull the image: docker pull ghcr.io/bigjk/snd:master
2. Run the container with the following parameters:
   • -p 7123:7123: Maps the web interface port.
   • --device=/dev/bus/usb: Replace this with the actual device path of your USB/Serial printer.
   • --group-add uucp: Replace uucp with the group (or GID) allowed to read your device file. You can find the correct group using $(stat -c "%g" /dev/bus/usb).
   • -v /some/place/to/persist:/app/userdata: Replace /some/place/to/persist with a local directory to persist user data.
3. Access the interface at http://127.0.0.1:7123.

Docker Compose Configuration

You can use the following docker-compose.yml structure:

version: "3"
services:
  snd:
    image: ghcr.io/bigjk/snd:master
    ports:
      - "7123:7123"
    devices:
      - "/dev/bus/usb"
    group_add:
      - uucp
    volumes:
      - "/some/place/to/persist:/app/userdata"

To build the Android Host, you must first build the frontend, then bind the Go mobile library, and finally assemble the Android app using Gradle.

1. Build the Frontend

Navigate to the frontend directory and use bun to build the assets:

cd frontend
bun run build

2. Build the gomobile AAR

From the repository root, use gomobile bind to create the .aar file. This requires the Android NDK to be installed.

go get -tool golang.org/x/mobile/cmd/gobind
gomobile bind -target=android -androidapi 26 -o android/app/libs/sndmobile.aar ./mobile

3. Assemble the Android App

Navigate to the android directory and use Gradle to build the debug APK:

cd android
./gradlew assembleDebug

Automated Build

You can run the entire process (frontend build, gomobile binding, and Gradle task) in one step from the repository root using the provided build script:

./build_android.sh

A SessionGrid is a collection of elements used to define a sequence of actions or templates. It consists of a name and an array of elements. Elements can be individual GridElement types or a GridLinearExecution block which allows for repeating a sequence of elements.

GridElement Types

• GridTemplateElement: Uses a templateId to reference a specific template. Can optionally include a dataSourceId, entryId, or configName.
• GridGeneratorElement: Uses a generatorId to trigger a generator. Can optionally include configName and aiEnabled.
• GridPrinterCommandElement: Executes a physical printer command. The command must be one of 'cut', 'drawer1', or 'drawer2'.

Execution Patterns

• GridLinearExecution: A container that allows you to group elements and optionally specify a repeat count to execute that group multiple times.

const session: SessionGrid = {
  name: "Example Session",
  elements: [
    {
      templateId: "template-123",
      color: "#ff0000"
    },
    {
      repeat: 3,
      elements: [
        { command: "cut" },
        { generatorId: "gen-abc", aiEnabled: true }
      ]
    }
  ]
};

The SndAPI class provides a programmatic interface to the Sales & Dungeon API. It is automatically generated from the API definition.

Initialization

To use the SDK, initialize the SndAPI class with the base_url of your API instance. A common default is http://127.0.0.1:7123.

API Methods

Methods are generated based on the API endpoints. Each method performs a POST request to an api/ endpoint and returns the JSON response.

Data Types

The SDK maps Go/SND types to Python types as follows:

• string $\rightarrow$ str
• int $\rightarrow$ int
• float $\rightarrow$ float
• bool $\rightarrow$ bool
• map or interface {} $\rightarrow$ dict
• []T (slices) $\rightarrow$ list of T
• snd.TypeName $\rightarrow$ dict [snd type type_name]

import requests

# Example of how the generated SDK is structured
class SndAPI:
    def __init__(self, base_url):
        """
        Initialize the Sales & Dungeon API class with the base URL of the API.

        Parameters:
        - base_url (str): The base URL of the API. Most likely "http://127.0.0.1:7123"
        """
        self.base_url = base_url

    def _make_request(self, endpoint, method='GET', params=None):
        url = f"{self.base_url}/{endpoint}"
        if method == 'GET':
            response = requests.get(url, params=params)
        elif method == 'POST':
            response = requests.post(url, json=params)
        elif method == 'DELETE':
            response = requests.delete(url, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        if response.status_code == 200:
            return response.json()
        else:
            response.raise_for_status()

    # Example of a generated method
    def example_action(self, arg0, arg1):
        """
        Perform an action using the example_action API endpoint.

        Parameters:
        - arg0 (str): parameter
        - arg1 (int): parameter
        """
        endpoint = "api/example_action"
        return self._make_request(endpoint, method='POST', params=[arg0, arg1])