Docker Support

The abstraction mechanisms of Docker make certain types of hardware integration quite challenging in Docker. As long as your device is not removed and reinserted during the lifetime of your container you will likely not have any issues. However, certain operations like our flash update process generate USB reset event that will confound Docker. This tutorial explains solutions for this particular problem.

Important

Only Linux hosts are supported for Docker containers

Privileged

The most reliable implementation we've tested leverages the --privileged flag and the mounting of /dev/bus/usb volume from host to container. Your results may vary and you may find this to be unnecessary for your environment.

sudo docker run --rm -it \
     -v /dev/bus/usb:/dev/bus/usb \
     --privileged \
     <YOUR_CONTAINER>:<VERSION>

Host Permissions

Your host system may require additional permissions or even udev rules in order to reliably attach to your Reliance Thermal Printer. This is typically achieved by adding your user to the dialout group or equivalent for your environment. Another option is to create a udev rule, /etc/udev/rules.d/99-udev.rules with the following contents.

# Reliance Thermal Printer HID interface
SUBSYSTEM=="usb", ATTRS{idVendor}=="0425", ATTRS{idProduct}=="8147", MODE="0666"

Special Configurations

A pre-made configuration for the Debian Stretch Docker image can be configured with the following in your application start up code.

PTIRelianceLib.Library.Options = PTIRelianceLib.LibraryOptions.DockerLinuxStretch;

Library Customization

PTIRelianceLib is designed to support as many operating systems as possible. We try to support as much as possible with defaults but in some cases, there are outliers that we need to make special accommodations for without affecting other systems.

These options are accessible in the LibraryOptions class and should be attached to the global Library.

Connection Failures

The most common issue users experience with hardware SDKs is with the initial connection. This can be due to driver issues, operating system configuration, or many other possibilities. In this library, there are two likely causes for your connection issue.

  • 1 Incorrect native library version: We use HIDAPI to access the Reliance Printer as a HID USB device. Our nuget package installs the native library for Windows(x86 and x64), Linux x64, ans OSX x64. If you use a different CPU or operating system, your environment is not supported at this time. Contact us!
  • 2 Your operating system is not propagating device information in a standard way. This is common in Docker containers.

If your system is supported and you've followed all the tutorials, read on to learn how to customize PTIRelianceLib for your environment.

Options

LibraryOptions provides following properties:

  • HidCleanupDelayMs: Used to ensure operating system is given enough time to remove and create device handles
  • HidReconnectDelayMs: Used to give the operating system more time to enumerate devices during reconnection
  • HidFlushStructuresOnEnumError: When no devices are found during enumeration, this may indicate stale device data is being forwarded by your system. Set this flag to force receipt of fresh information.

Relation to Flash Update

The Reliance Thermal Printer executes a reboot at the start and end of the flash update process. This generates USB disconnect and reconnect events which, as stated above, can be tricky on some systems. If you are having trouble flash updating for your system, take as look at some of the preconfigured settings available in LibraryOptions such as DockerLinuxStretch.

Warning

Exceptions

For clarity, exception handling has been elided. It is advisable to wrap any ReliancePrinter method calls in a try/catch block for PTIException.