zebra-day 1.0.2__py3-none-any.whl → 2.1.4__py3-none-any.whl

zebra_day/cli/printer.py

@@ -2,14 +2,11 @@
 
 import json
 import socket
-from typing import Optional
 
 import typer
 from rich.console import Console
 from rich.table import Table
 
-from zebra_day import paths as xdg
-
 printer_app = typer.Typer(help="Printer fleet management commands")
 console = Console()
 
@@ -19,7 +16,7 @@ def _get_local_ip() -> str:
     try:
         s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
         s.connect(("8.8.8.8", 80))
-        ip = s.getsockname()[0]
+        ip: str = s.getsockname()[0]
         s.close()
         return ip
     except Exception:
@@ -28,9 +25,13 @@ def _get_local_ip() -> str:
 
 @printer_app.command("scan")
 def scan(
-    ip_stub: Optional[str] = typer.Option(None, "--ip-stub", "-i", help="IP stub to scan (e.g., 192.168.1)"),
+    ip_stub: str | None = typer.Option(
+        None, "--ip-stub", "-i", help="IP stub to scan (e.g., 192.168.1)"
+    ),
     wait: float = typer.Option(0.25, "--wait", "-w", help="Seconds to wait per IP probe"),
-    lab: str = typer.Option("scan-results", "--lab", "-l", help="Lab name to assign found printers"),
+    lab: str = typer.Option(
+        "scan-results", "--lab", "-l", help="Lab name to assign found printers"
+    ),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
     """Scan network for Zebra printers."""
@@ -45,6 +46,7 @@ def scan(
 
     try:
         import zebra_day.print_mgr as zdpm
+
         zp = zdpm.zpl()
         zp.probe_zebra_printers_add_to_printers_json(
             ip_stub=ip_stub,
@@ -56,12 +58,14 @@ def scan(
         if hasattr(zp, "printers") and "labs" in zp.printers and lab in zp.printers["labs"]:
             for name, info in zp.printers["labs"][lab].items():
                 if isinstance(info, dict) and info.get("ip_address") not in ["dl_png"]:
-                    found.append({
-                        "name": name,
-                        "ip": info.get("ip_address"),
-                        "model": info.get("model", "unknown"),
-                        "serial": info.get("serial", "unknown"),
-                    })
+                    found.append(
+                        {
+                            "name": name,
+                            "ip": info.get("ip_address"),
+                            "model": info.get("model", "unknown"),
+                            "serial": info.get("serial", "unknown"),
+                        }
+                    )
 
         if json_output:
             console.print(json.dumps(found, indent=2))
@@ -82,17 +86,18 @@ def scan(
             console.print(json.dumps({"error": str(e)}))
         else:
             console.print(f"[red]✗[/red] Scan error: {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
 
 @printer_app.command("list")
 def list_printers(
-    lab: Optional[str] = typer.Option(None, "--lab", "-l", help="Filter by lab name"),
+    lab: str | None = typer.Option(None, "--lab", "-l", help="Filter by lab name"),
     json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ):
     """List configured printers."""
     try:
         import zebra_day.print_mgr as zdpm
+
         zp = zdpm.zpl()
 
         printers = []
@@ -102,13 +107,15 @@ def list_printers(
                     continue
                 for name, info in lab_printers.items():
                     if isinstance(info, dict):
-                        printers.append({
-                            "lab": lab_name,
-                            "name": name,
-                            "ip": info.get("ip_address", "unknown"),
-                            "model": info.get("model", "unknown"),
-                            "styles": info.get("label_zpl_styles", []),
-                        })
+                        printers.append(
+                            {
+                                "lab": lab_name,
+                                "name": name,
+                                "ip": info.get("ip_address", "unknown"),
+                                "model": info.get("model", "unknown"),
+                                "styles": info.get("label_zpl_styles", []),
+                            }
+                        )
 
         if json_output:
             console.print(json.dumps(printers, indent=2))
@@ -128,7 +135,7 @@ def list_printers(
         for p in printers:
             styles = ", ".join(p["styles"][:2])
             if len(p["styles"]) > 2:
-                styles += f" (+{len(p['styles'])-2})"
+                styles += f" (+{len(p['styles']) - 2})"
             table.add_row(p["lab"], p["name"], p["ip"], p["model"], styles)
         console.print(table)
 
@@ -137,7 +144,7 @@ def list_printers(
             console.print(json.dumps({"error": str(e)}))
         else:
             console.print(f"[red]✗[/red] Error: {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
 
 @printer_app.command("test")
@@ -149,10 +156,11 @@ def test_print(
     """Send a test print to a specific printer."""
     try:
         import zebra_day.print_mgr as zdpm
+
         zp = zdpm.zpl()
 
         console.print(f"[cyan]→[/cyan] Sending test print to {printer_name}...")
-        result = zp.print_zpl(
+        zp.print_zpl(
             lab=lab,
             printer_name=printer_name,
             uid_barcode="TEST-PRINT",
@@ -160,9 +168,8 @@ def test_print(
             alt_b="zebra_day CLI",
             label_zpl_style=label_style,
         )
-        console.print(f"[green]✓[/green] Test print sent successfully")
+        console.print("[green]✓[/green] Test print sent successfully")
 
     except Exception as e:
         console.print(f"[red]✗[/red] Print error: {e}")
-        raise typer.Exit(1)
-
+        raise typer.Exit(1) from None

zebra_day/cli/template.py

@@ -1,10 +1,12 @@
 """ZPL template management commands for zebra_day CLI."""
 
+from __future__ import annotations
+
 import json
 import os
 import subprocess
 from pathlib import Path
-from typing import Optional
+from typing import Any
 
 import typer
 from rich.console import Console
@@ -37,7 +39,7 @@ def _get_template_dirs() -> list[Path]:
     return dirs
 
 
-def _find_template(name: str) -> Optional[Path]:
+def _find_template(name: str) -> Path | None:
     """Find a template file by name."""
     for template_dir in _get_template_dirs():
         # Try exact match
@@ -59,18 +61,20 @@ def list_templates(
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show full paths"),
 ):
     """List available ZPL templates."""
-    templates = []
+    templates: list[dict[str, Any]] = []
 
     for template_dir in _get_template_dirs():
         for f in template_dir.iterdir():
             if f.is_file() and not f.name.startswith("."):
                 if f.suffix in [".zpl", ".txt", ""] or f.name.startswith("zpl_"):
-                    templates.append({
-                        "name": f.stem,
-                        "path": str(f),
-                        "size": f.stat().st_size,
-                        "source": "user" if "zebra_day" not in str(template_dir) else "package",
-                    })
+                    templates.append(
+                        {
+                            "name": f.stem,
+                            "path": str(f),
+                            "size": f.stat().st_size,
+                            "source": "user" if "zebra_day" not in str(template_dir) else "package",
+                        }
+                    )
 
     # Dedupe by name, prefer user templates
     seen = {}
@@ -107,7 +111,7 @@ def list_templates(
 @template_app.command("preview")
 def preview(
     template_name: str = typer.Argument(..., help="Template name to preview"),
-    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output PNG file path"),
+    output: str | None = typer.Option(None, "--output", "-o", help="Output PNG file path"),
 ):
     """Generate a PNG preview of a ZPL template."""
     template_path = _find_template(template_name)
@@ -119,6 +123,7 @@ def preview(
 
     try:
         import zebra_day.print_mgr as zdpm
+
         zp = zdpm.zpl()
 
         # Read template
@@ -130,18 +135,18 @@ def preview(
         else:
             output_path = Path(output)
 
-        result = zp.generate_label_png(zpl_content, str(output_path), False)
+        zp.generate_label_png(zpl_content, str(output_path), False)
         console.print(f"[green]✓[/green] Preview generated: {output_path}")
 
     except Exception as e:
         console.print(f"[red]✗[/red] Preview error: {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
 
 @template_app.command("edit")
 def edit(
     template_name: str = typer.Argument(..., help="Template name to edit"),
-    editor: Optional[str] = typer.Option(None, "--editor", "-e", help="Editor command"),
+    editor: str | None = typer.Option(None, "--editor", "-e", help="Editor command"),
 ):
     """Open a ZPL template in an editor."""
     template_path = _find_template(template_name)
@@ -158,7 +163,7 @@ def edit(
         subprocess.run([editor, str(template_path)])
     except Exception as e:
         console.print(f"[red]✗[/red] Error opening editor: {e}")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
 
 @template_app.command("show")
@@ -173,4 +178,3 @@ def show(
 
     console.print(f"[dim]# {template_path}[/dim]\n")
     console.print(template_path.read_text())
-

zebra_day/cmd_mgr.py

@@ -1,17 +1,16 @@
 """
-  Tools to manage a zebra printer fleet and expose an API for routing print requests.
+Tools to manage a zebra printer fleet and expose an API for routing print requests.
 """
 
 import socket
 
-class ZebraPrinter:
 
+class ZebraPrinter:
     def __init__(self, ip_address, port=9100, buffer_size=1024):
         self.ip_address = ip_address
         self.port = port
         self.buffer_size = buffer_size
 
-        
     def send_command(self, command):
         with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
             s.connect((self.ip_address, self.port))
@@ -19,15 +18,13 @@ class ZebraPrinter:
             response = s.recv(self.buffer_size)
         return response.decode()
 
-    
     def get_configuration(self):
         """Retrieve printer configuration using ^HH command"""
         return self.send_command("^XA^HH^XZ")
 
-    
     def set_configuration(self, config):
         """
-        Set printer configuration. 
+        Set printer configuration.
         The `config` parameter should contain the necessary ZPL commands to adjust the configuration.
         After sending the configuration commands, the ^JUS command saves the configuration.
         """

zebra_day/docs/hardware_config_guide.md

@@ -0,0 +1,149 @@
+## Hardware
+
+### Zebra Printers
+* Printers will need to be able to secure an IP address either via a wired connection or via wireless.  The printers will need to be visible to the machine running this package in order to accept print requests. Further, there are tools to scan the local network and identify Zebra Printers. Identified printers are automatically configured for use by `zebra_day`.
+
+  * Network attached printers should be able to run w/out any connection to a PC/laptop. This affors much greater flexibility in placing print stations. In fact, `zebra_day` does not communicate with USB only printers.
+* The below zebra printer models have been tested, but any zebra printer able to obtain an IP address and accept `ZPL` should also work.
+* _IMPORTANT_, The initial configuration of zebra printers can be a little gnarly. I intend to add some notes on this topic soon. In the mean time, the GUI printer status report includes links to access the web server admin utility each zebra printer exposes.
+  * the printer admin UIs all use the default un/pw: `admin/1234`.
+    * The first thing I suggest when setting up a new printer is resetting the factory defaults - doable via the zebra printer admin UIs.
+  * Wired ethernet connections are advised for greater robustness.  Configure the wired network settings to obtain an IP automatically.  ask your network admins to set DNS rules which will assign the same IP to each printer.  You'll need to supply the printer MAC address to do this, which you can find on via each printers admin UI.
+    * __NOTE__ Sometimes these printers can not seem to obtain an IP with DHCP, this could be a router/hub issue, but sometimes you'll need to set the printer to a static IP.  This can be done via the printer admin UI. If the network config is saved with an error, you'll now need to connect to the printer via USB to reset (there might be a button seuquece cycle which can be hit to factory reset...).
+    * Wireless setup is _SUPER_ fussy. You'll need to know precisely what bands your router is running on, and the precise auth used. This can be done via the zebra printer admin UI, or when connected via a USB cable to a computer running a driver config program(not advised really).
+  * Next, you may have to mess around with calibration settings for label width and length.
+  * I have used this driver/config tool on a MAC when I have needed to connect to a printer via `USB`, [Peninsula Zebra Printer Driver](https://www.peninsula-group.com/install-zebra-printer-mac-osx/install-zebra-printer-mac-osx.html). I'm fairly sure there are several windows options.
+
+
+#### GX420d - wired, no LCD screen
+
+These printers are NOT reccomended b/c the lack of LCD screen makes them a pain to configure.  You will probably need to connect via USB to set good initial settings.  If you have the `zebra_day` UI running, try connecting the printer to the network and powering on, then run the zebra printer network scan.  If the printer is discovered, you're in luck and can admin it via the UI on the printer.
+
+* [Available From Amazon](https://www.amazon.com/gp/product/B07KCQ67Y1/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1)
+* Cost per printer : `$264.00`
+* [manual]()
+
+#### GX420d - wired, with LCD screen
+These are solid, but aging out and not as easy to find for sale.
+
+* [Available From Amazon](https://www.amazon.com/gp/product/B011Q95XX2/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1)
+* Cost per printer : `$425.00`
+* [manual]()
+
+#### ZD620d - wired and wireless, with color LCD screen
+These are solid, but aging out and not as easy to find for sale.
+
+* [Available From Amazon](https://www.amazon.com/gp/product/B07VHDR33Z/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1)
+* Cost per printer : `$331.00`
+* [manual]()
+
+#### Zebra QLn420 Direct Thermal Printer - Monochrome - Portable 
+
+* [Amazon](https://www.amazon.com/dp/B084P4KBWS?psc=1&ref=ppx_yo2ov_dt_b_product_details)
+* Cost per printer : `$136`
+* [manual]()
+
+#### Zebra - ZD620d Direct Thermal Desktop Printer with LCD Screen - Print Width 4 in - 203 dpi - Interface: WiFi, Bluetooth, USB, Serial, Ethernet - ZD62142-D01L01EZ
+
+* [Amazon](https://www.amazon.com/dp/B07VHDR33Z?psc=1&ref=ppx_yo2ov_dt_b_product_details)
+* Cost per printer : `$331`
+* [manual]()
+
+
+#### Zebra ZD620t Thermal Transfer Desktop Printer 203 dpi Print Width 4 in Ethernet Serial USB ZD62042
+<font color=magenta>note, this is a thermal transfer printer & requires ribbons to print</font>
+* [Amazon](https://www.amazon.com/dp/B08PW6ZRL6?psc=1&ref=ppx_yo2ov_dt_b_product_details)
+* Cost per printer : `$500`
+* [manual]()
+
+### Initial Printer Configuration
+Ideally, you will be able to use `zebra_day` to auto-detect printers on your network, and connect to each ones web based admin tool (links are presented on the [printer fleet summary page](), un/pw is `admin/1234` ). Failing this, you will need to connect via usb, [there are several drivers to choose from if this is necessary, I liked this one for a MAC](https://www.peninsula-group.com/mac-thermal-printer-driver/). The main changes to make (and do so after consulting each printers manual):
+  * reset to factory defaults.
+  * set the network settings (wired and wifi) & hard code IPs if needed. It is helpful if they retain the same IP over time.
+  * Set the media type to `web`, set behavior on close and restart to be calibrate.
+  * Once you begin printing, you might find you need to adjust the print width and length for some printers if they do not set properly during calibration.
+  * Increase the darkness.
+  * Decrease print speed, `IPS` to 2 or 3.
+
+##### Reference Printer Config Reports
+* [GX420d - printer](zebra_day/imgs/legacy/gx420d_printer_config.png) .... [GX420d - network](zebra_day/imgs/legacy/gx420d_network_config.png)
+* [ZD620 - printer](zebra_day/imgs/legacy/zd620_printer_config.png) .... [ZD620 - network](zebra_day/imgs/legacy/zd620_network_config.png)
+
+
+  
+
+### Thermal Transfer Ribbons
+Also require distinct label stock from the direct thermal transfer printer labels.
+
+* [Amazon](https://www.amazon.com/dp/B07FX3PJ2M?psc=1&ref=ppx_yo2ov_dt_b_product_details)
+* Cost per roll: `$7`
+
+
+# Label Stock
+The `zebra_day` code can easily manage a printer fleet comprised of different printing mechanism. 
+
+> Thermal Transfer vs. Direct Thermal Transfer Labels
+  * Printers are only capable of printing using one or the other method only.
+
+  > Direct thermal transfer labels require no ribbon, cheaper, can be less robust in some situations, speciality use case label stock mfgs are numerous. 
+
+  > Thermal transfer labels require a ribbon, can be more durable, prone to smudging, more costly
+  
+### Aegis Labels
+For general purpose use. Very inexpensive and easy to source.
+
+#### 2in x 1in - Direct TT
+Good for paperwork, some larger tubes.
+
+* [Amazon](https://www.amazon.com/gp/product/B098Z8JYZC/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&th=1)
+* Cost per roll : `$3.21`
+
+#### 2in x 0.5in - Direct TT
+Good for smaller tubes, or tubes that already have space taken up by labels.
+
+* [Available On Amazon](https://www.amazon.com/gp/product/B098Z8JYZC/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&th=1)
+* Cost per roll : `$3.25`
+
+
+### [Labtag](http://www.labtag.com)
+
+#### 2in x 1in / a few colors / cryo - Direct TT
+
+* [LabTag](https://www.labtag.com/shop/product/cryogenic-direct-thermal-labels-2-x-1-dfp-dfpc-28-2/?attribute_pa_core-size=1&attribute_pa_qty-uom=1000&attribute_pa_color=white)
+* Cost per roll : `$81`
+
+#### 2in x 0.25in / plate style / cryo - Direct TT
+
+* [LabTag](https://www.labtag.com/shop/product/cryogenic-direct-thermal-labels-2-x-0-25-dfp-227/?attribute_pa_core-size=1&attribute_pa_qty-uom=2000)
+* Cost per roll	: `$67`
+
+#### small tube w/dot / cryo - Direct TT
+
+* [LabTag](https://www.labtag.com/shop/product/cryogenic-direct-thermal-labels-1-25-x-0-625-0-375-dfp-103/?attribute_pa_core-size=1&attribute_pa_qty-uom=2000)
+* Cost per roll	: `$105`
+
+#### 2in x 1in / cryo / many colors - Thermal Transfer
+
+* [LabTag](https://www.labtag.com/shop/product/cryogenic-barcode-labels-2-x-1-jtta-28/?attribute_pa_core-size=1&attribute_pa_qty-uom=2000&attribute_pa_color=white)
+* Cost per roll : `$117`
+
+
+#### 2in x 0.25in / plate / cryo - Thermal Transfer
+
+* [LabTag](https://www.labtag.com/shop/product/thermal-transfer-cryogenic-labels-for-frozen-vials-surfaces-2-x-0-25-uc-227/?attribute_pa_core-size=1&attribute_pa_qty-uom=2000)
+* Cost per roll : `$80`
+
+
+# Barcode Scanners
+
+## Tera 1d, 2d, QR  scanner. Corded and bluetooth and wireless
+Programable and well supported/adopted.
+
+* [Available From Amazon](https://www.amazon.com/dp/B0953FJZDG?psc=1&ref=ppx_yo2ov_dt_b_product_details)
+* Cost per scanner : `$63.00`
+
+## Tera Mini 1d 2d QR. Corded and wireless and bluetooth.
+_experimenting_... tiny handheld pretty well behaving non-corded scanner.
+
+* [Available From Amazon](https://www.amazon.com/dp/B08NDFWFKJ?psc=1&ref=ppx_yo2ov_dt_b_product_details)
+* Cost per Scanner : `$38.00`

zebra_day/docs/programatic_guide.md

@@ -0,0 +1,181 @@
+# Library Usage
+<a href=../../README.md ><img src="http://flux.glass/format_gh_text?txt=back+home&bg_color=%23443636&txt_color=%232eecef&font=Monoid-Regular-HalfTight-Dollar-0-1-l&font_size=12&width=95&ret_type=img" /></a>
+## Quickstart
+
+```python
+import zebra_day.print_mgr as zdpm
+
+zlab = zdpm.zpl()
+
+zlab.probe_zebra_printers_add_to_printers_json('192.168.1')  # REPLACE the IP stub with the correct value for your network. This may take a few min to run.  !! This command is not required if you've sucessuflly run the quickstart already, also, won't hurt.
+
+print(zlab.printers)  # This should print out the json dict of all detected zebra printers. An empty dict, {}, is a failure of autodetection, and manual creation of the json file may be needed. If successful, the lab name assigned is 'default', this may be edited later.
+# The json will look something like this (v2.0.0 schema with nested printers)
+## {'schema_version': '2.0.0', 'labs': {'default': {'lab_name': 'Default', 'printers': {'192.168.1.7': {'ip_address': '192.168.1.7', ...}}}}}
+
+# Assuming a printer was detected, send a test print request. Using the 'lab', 'printer' and 'label_zpl_style' above (you'd have your own IP/Name, other values should remain the same for now. There are multiple label ZPL formats available, the test_2inX1in is for quick testing & only formats in the two UID values specified.
+
+zlab.print_zpl(lab='default', printer_name='192.168.1.7', label_zpl_style='test_2inX1in', uid_barcode="123aUID")
+# ZPL code sent successfully to the printer!
+# Out[13]: '^XA\n^FO235,20\n^BY1\n^B3N,N,40,N,N\n^FD123aUID^FS\n^FO235,70\n^ADN,30,20\n^FD123aUID^FS\n^FO235,115\n^ADN,25,12\n^FDalt_a^FS\n^FO235,145\n^ADN,25,12\n^FDalt_b^FS\n^FO70,180\n^FO235,170\n^ADN,30,20\n^FDalt_c^FS\n^FO490,180\n^ADN,25,12\n^FDalt_d^FS\n^XZ'
+```
+
+## Primary Operations
+
+### Init Object
+> def zpl():
+
+
+  ```python
+  import zebra_day.print_mgr as zdpm
+  
+  zlab = zdpm.zpl()
+  ```
+
+  The IP of the machine creating the obj is determined, and the default printer config.json is read.
+
+
+### Load/Save/Clear Printer Config json
+
+> As of 0.6.0, printer configuration is stored in XDG-compliant locations:
+> - **Linux**: `~/.config/zebra_day/printer_config.json`
+> - **macOS**: `~/Library/Preferences/zebra_day/printer_config.json`
+>
+> Use `zday info` to see the exact path on your system.
+
+```python
+# These methods now use the XDG paths automatically
+zlab.save_printer_json()
+zlab.load_printer_json()
+zlab.clear_printers_json()
+zlab.replace_printer_json_from_template()
+```
+
+When clearing or writing a new config.json, the existing one is saved to a backup location. Users can open these and effectively rollback if errors are made. Replace from template means overwriting the active one with the json example file which accompanies the repo.
+
+
+### Scan Local Network For Zebra Printers
+  >  def probe_zebra_printers_add_to_printers_json(self, ip_stub="192.168.1", scan_wait="0.25",lab="scan-results"):
+  
+### Check label styles allowed for a lab    
+> def get_valid_label_styles_for_lab(self,lab=None):
+
+A never quite implemented idea.
+
+### Produce a ZPL string which will be sent to a printer
+
+>  def formulate_zpl(self,uid_barcode=None, alt_a=None, alt_b=None, alt_c=None, alt_d=None, alt_e=None, alt_f=None, label_zpl_style=None):
+
+  * The `lab` & `printer_name` are used to resolve the IP address for the printer this tuple identify.
+  * `label_zpl_style` is used to find the `zpl` template file the remaining values passed in are templated in to.
+  * `uid_barcode` is the value which is encoded as a barcode and presented in human readable form. The way this value is displayed will vary by template.
+  * `alt_[a-f]` these are used diferently, or not at all, depending on the zpl template.  
+
+### Send ZPL To Zebra To Print A Label
+> def print_zpl(self, lab=None, printer_name=None, uid_barcode='', alt_a='', alt_b='', alt_c='', alt_d='', alt_e='', alt_f='', label_zpl_style=None, client_ip='pkg', print_n=1):
+
+With the ZPL string produced, determine the printer IP and send the string to it.
+
+### Send ZPL To PDF Generation Service
+>  def generate_label_png(self,zpl_string=None, png_fn=None):
+
+Rather than print a physical label, produce a `png`... this is most helpful when we get to the UI.
+
+## Data Structures
+
+### Printer json (v2.0.0 Schema)
+This is the file which describes the printer fleet. It may be manually edited or edited via the GUI.
+
+```json
+{
+    "schema_version": "2.0.0",
+    "labs": {
+        "default": {
+            "lab_name": "Default",
+            "available_locations": ["Bench A", "Bench B"],
+            "printers": {
+                "192.168.1.7": {
+                    "ip_address": "192.168.1.7",
+                    "printer_name": "Main Lab Printer",
+                    "lab_location": "Bench A",
+                    "manufacturer": "zebra",
+                    "model": "ZD620",
+                    "serial": "12345",
+                    "label_zpl_styles": ["tube_2inX1in", "plate_1inX0.25in"],
+                    "default_label_style": "tube_2inX1in",
+                    "print_method": "socket",
+                    "arp_data": "",
+                    "notes": "Primary sample printer"
+                }
+            }
+        }
+    }
+}
+```
+
+**Schema v2.0.0 Changes:**
+- `labs` now contains nested `printers` object (not flat printer entries)
+- Added `lab_name` and `available_locations` at lab level
+- Added `printer_name`, `lab_location`, `manufacturer`, `default_label_style`, `notes` at printer level
+- Added `schema_version` at root level
+
+The `lab` key in this example is `default`, which is the lab name assigned when autodetect runs. These names are editable via the GUI. Printers are nested under the `printers` key within each lab.
+
+### Rendering ZPL to PNG (without printing)
+
+To generate a PNG preview of a label without sending to a printer, use the `/api/v1/render` endpoint:
+
+```bash
+# Render using a template
+curl -X POST "https://localhost:8118/api/v1/render" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "template_name": "tube_2inX1in",
+    "uid_barcode": "SAMPLE123",
+    "alt_a": "Field A",
+    "alt_b": "Field B"
+  }' \
+  --output label.png
+
+# Render raw ZPL content
+curl -X POST "https://localhost:8118/api/v1/render" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "zpl_content": "^XA^FO50,50^ADN,36,20^FDHello World^FS^XZ"
+  }' \
+  --output label.png
+```
+
+The render endpoint returns a PNG image directly. This is useful for:
+- Previewing labels before printing
+- Generating label images for documentation
+- Testing ZPL templates without physical printers
+
+### ZPL Template Files
+These are template files for various different label styles. These may be manually edited (but its a nicer expereience using the UI)
+
+* Template files are easiest to design via the UI. The ZPL format is very old school word processor vibes.
+
+```text
+^XA
+^FO200,20
+^BY1
+^B3N,N,40,N,N
+^FD{uid_barcode}^FS
+^FO200,70
+^ADN,30,20
+^FD{uid_barcode}^FS
+^FO460,18
+^ADN,24,14
+^FD{alt_a}^FS
+^FO515,62
+^ADN,40,26
+^FD{alt_b}^FS
+^XZ    
+```
+
+* The `{}` format keys match those from above in the zpl string formulation call.
+* [ZPL docs](https://labelary.com/zpl.html)
+* This ZPL creates this label:<ul>
+
+    <img width="312" alt="zpl_exa" src="https://github.com/Daylily-Informatics/zebra_day/assets/4713659/9d2b53b3-03d0-4095-9622-64273734ff76">

zebra_day/docs/uid_screed_light.md

@@ -0,0 +1,38 @@
+# Unique Identifiers **** D R A F T NOTES ****
+
+## Maxims
+
+### Be unique in the namespace... if possible, even outside the namespace.
+  * Be extremely cautious when working with test and sandbox environments which produce potentially overlapping UIDs to your production systems. Better yet, do not produce UIDs which overlap with other systems you control. `barcode labels IRL`.
+  * Issued by a single UID authority.
+  
+### Absolutely should not change once issued.
+
+### Each distinct thing deserves its own UID.
+  * corrolaries:
+    * copies of	things are now distinct	things,	and should have	their own UID (metadata and relationships should be stored indicating relationships to other UIDs).
+      *	In other words __at all	costs, avoid re-using UIDs for children	of things. This	may momentarily	be convenient, but I can promise you in	the end, you'll	have more than made up for the immediate convenience with an unecessarily fragile and opaque process/system.
+
+### Encode only the unique ID
+#### Vigourously avoid encoding any meta data regarding the thing identied by a UID in the UID. Similarly, avoid encoding process/state information.
+
+* There is one exception, 'enterprise UIDs', with a brief prefix indicating object have not been a problem in my experience ([see stripe thinking on this](stripe.com)). These prefixes even offer a benefit when talking about object classes, as well as speeding up certain database queries.
+* A few tests to apply when this temptation presents itself (and it will, more than you'd like):
+  * Is the information being added to the UID mutable ever? And if the answer is 'almost never' or 'it should not happen(but not actively blocked by a system)', this is BAD.  What if there was a clerical error post UID assignment and now the UID does not reflect the corrected info? Chage the UID? (bad idea, see above)
+  * Is there a better way to accomplish whatever use case having the additional data in the UID is attempting to meet (in effectively every situation I've encountered, the answer is yes). Explore how to better serve this use case with other solutions.
+      
+
+### Use only alpha numeric characters, ideally all uppercase alpha, no special characters.
+* This means no `-`
+
+### Under no circumstances should you add 0's as a prefix to a number being used as a UID
+* If a UID is randomly assigning alphanumeric and leading 0s happen to be assigned, is the only exception I can imagine.  Otherwise, this is a huge driver of errors, and mostly of the silent variety.
+  * Consider this:  are `EX001` and `EX1` the same? What about `EX0001`?  The answer is that to software at least, these are each unique UIDs. To people, these more often than not are all `EX1`, and are spoken about this way very frequently. Also -  the leading zeros are often omitted when writing the UID down.
+    * The arguments for using padded zeros boil down to `they look good in spreadsheets`. Which is not a very compelling reason to adopt a very error prone and fragile design element.
+      * What happens when you outgrow the pre-establised number of characters?
+      * many s/w systems will auto trim the leading zeros.
+      * some barcode scanners will trim leading zeros.
+      * What if leading zeros are adjacent to the character 'O'?
+
+### Reading and writing UIDs should not be done by hand
+* label printers and scanners.