ptouch-api

Simple REST api for Brother P-touch label printers.

Installation

You can download pre-built binaries from the releases page or build it yourself using cargo build.

Configuring

[listen]
# by default the server listens over tcp
# address = "0.0.0.0" # defaults to "127.0.0.1"
# port = 1234 # defaults to 7074
# you can set it to listen over a unix socket instead.
socket = "/run/ptouch-api.sock"

In additional to the listen configuration, the server will automatically detect if it get's activated trough systemd socket activation and takes the provided socket.

Usage

ptouch-api [--config config.toml]

Permissions

You'll need to either run ptouch-api as root or setup a udev rule to change the owner or permissions to allow ptouch-api to access the label printer over usb.

See 51-ptouch-api.rules for an example udev rule, placing this into /etc/udev/rules.d and adjusting the username as desired should give the specified user access to the ptouch printer.

Alternatively you can use 51-ptouch-api-everyone.rules to give all users on the system access to the label printer.

API

• GET /status: get printer and tape status for details about the fields.
• PUT /print: print the uploaded image, supports png, jpg and bmp

Status

The returned status is a json with the following fields:

• media_width: width of the loaded tape in mm.
• pixel_width: the width of the printed image in pixels.
• margin_width: the left and right margin on the tape that can't be printed.
• media_type: material type of the loaded tape.
• text_color: text color for the loaded tape.
• tape_color: tape color for the loaded tape.

(note that the tape is assumed to be horizontal here, so "width" is the short short direction)

Supported printers

The following printers are currently supported

• PT-9200DX
• PT-2300
• PT-2420PC
• PT-2450PC
• PT-1950
• PT-2700
• PT-1230PC
• PT-2430PC
• PT-1230PC_PLite
• PT-2430PC_PLite
• PT-2730
• PT-H500
• PT-E500
• PT-P700
• PT-P750W
• PT-P700_PLite
• PT-P750W_PLite
• PT-D410
• PT-D450
• PT-D460BT
• PT-D600
• PT-D610BT
• PT-P710BT

NixOs module

For NixOs users, a module is available as a flake that includes everything needed run the api.

{
  inputs.ptouch-api.url = "git+ssh://git@codeberg.org/icewind/ptouch-api.git";

  outputs = { self, nixpkgs, ptouch-api }: {
    nixosConfigurations.my-machine = nixpkgs.lib.nixosSystem {
      modules =
        [
          ptouch-api.nixosModules.default
          ({config, ...}: {
            # enable the api service and setup the udev rules
            services.ptouch-api = {
              enable = true;
              # socket = "/path/for/socket/to/listen"; # defaults to /run/ptouch-api/ptouch-api.sock
            };
            # expose the api to the outside world
            services.nginx = {
              virtualHosts."ptouch.example.com" = {
                locations."/" = {
                  proxyPass = "http://unix://${config.services.ptouch-api.socket}";
                };
              };
            };
          })
          # ... other configuration ...
        ];
    };
  };
}