Integrate voltionX

How the SDK works

The SDK decodes entirely on your machine. Your images never leave your network, scanning keeps working if your internet drops, and there is no per-scan fee — you pay per machine, on the interval your plan uses.

Your licence key is checked offline using a signature. In the background the SDK also registers the machine and checks the licence is still valid, but that never blocks a scan: if our servers are unreachable, you carry on scanning.

1. What you received

2. Install

Python 3.9 or newer. OpenCV, NumPy, SciPy and cryptography install with the package — nothing else to set up.

python -m venv venv
# if PowerShell refuses to run the activate script:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
venv\Scripts\Activate.ps1

python3 -m venv venv
source venv/bin/activate

curl.exe -O -J "https://api.yourdomain.com/v1/sdk/download?key=YOUR_KEY"

curl -O -J "https://api.yourdomain.com/v1/sdk/download?key=YOUR_KEY"

pip install dotcode_sdk-1.0.0-py3-none-any.whl

# this session only
$env:DOTCODE_LICENSE_KEY = "YOUR_KEY"

# or permanently, for this user
[Environment]::SetEnvironmentVariable("DOTCODE_LICENSE_KEY", "YOUR_KEY", "User")

export DOTCODE_LICENSE_KEY="YOUR_KEY"          # this session
echo 'export DOTCODE_LICENSE_KEY="YOUR_KEY"' >> ~/.bashrc  # permanently

$env:DOTCODE_CA_BUNDLE = "C:\path\to\cert.pem"

export DOTCODE_CA_BUNDLE="/path/to/cert.pem"

3. Check it works

Run this before writing any of your own code. It answers every question you would otherwise have to ask support.

check_setup.pyimport datetime, os, time
from dotcode_sdk import Scanner, __version__

print("SDK version:", __version__)

scanner = Scanner(license_key=os.environ["DOTCODE_LICENSE_KEY"])
print("Licensed to:", scanner.license.org)
print("Plan       :", scanner.license.plan, "|", scanner.license.seats, "machines")
print("Expires    :", datetime.date.fromtimestamp(scanner.license.exp))

result = scanner.decode("barcode.png")
print("Decode     :", "OK" if result.ok else "FAILED", "-", result.text)

time.sleep(2)                    # registration happens in the background
print("Reporting  :", "OK" if scanner.cloud_ok else "NOT REACHING SERVER")
if not scanner.cloud_ok:
    print("            ", scanner.cloud_error)
scanner.close()

All five lines healthy looks like this:

SDK version: 1.0.0
Licensed to: Acme Tobacco Ltd
Plan       : pro | 10 machines
Expires    : 2027-07-31
Decode     : OK - 01095011015300031725013110ABC123
Reporting  : OK

4. Your first scan

Three lines. This is the whole integration:

first_scan.pyimport os
from dotenv import load_dotenv       # pip install python-dotenv
from dotcode_sdk import Scanner

load_dotenv()                        # reads DOTCODE_LICENSE_KEY from .env

scanner = Scanner(license_key=os.environ["DOTCODE_LICENSE_KEY"])
result  = scanner.decode("pack.png")

print(result.ok, result.text, result.format, result.elapsed_ms)
# True  01095011015300031725013110ABC123  DotCode  14.2

decode() accepts three kinds of input, so it drops into whatever you already have:

scanner.decode("pack.png")              # a file path
scanner.decode(open("pack.png","rb").read())  # raw bytes (e.g. from a queue)
scanner.decode(frame)                     # a numpy array, straight from OpenCV

What you get back

5. Raw text or GS1 fields

Most DotCodes on tobacco and pharmaceutical packaging don't carry free text — they carry a GS1 element string: a run of (identifier, value) pairs with no visible separators. Reading a GTIN or an expiry date out of that by eye is a good way to make a mistake, so you get both views.

result.text is always the raw payload, exactly as encoded:

01095011015300031725013110ABC123<GS>21SN9

result.gs1 is the same data, parsed:

structured.pyresult = scanner.decode("pack.png")

print(result.text)              # raw, always available

if result.gs1:                  # None when the code is plain text
    for element in result.gs1["elements"]:
        print(element["ai"], element["label"], element["value"])
    # 01   GTIN          09501101530003
    # 17   Expiry date   250131
    # 10   Batch/Lot     ABC123
    # 21   Serial number SN9

# or reach for one field directly
gtin   = result.field("01")     # "09501101530003"
batch  = result.field("10")     # "ABC123"
serial = result.field("21")     # "SN9"
print(result.fields)            # the whole dict at once

Dates come back both ways

GS1 dates are YYMMDD. The raw value is preserved and an ISO date is added, with the century resolved by the GS1 rule and a day of 00 read as "end of that month":

{"ai": "17", "label": "Expiry date",
 "value": "250131",          # as encoded
 "formatted": "2025-01-31"}  # ready to compare or store

GTIN check digits are verified too — a misread shows up as "09501101530004 (check digit mismatch)" rather than passing silently into your database.

6. A real production line

Create the scanner once when your program starts and reuse it — not per frame. Building it verifies the licence and starts background threads, so doing that in a loop is wasteful.

line_worker.pyimport os, cv2, logging
from dotcode_sdk import Scanner, LicenseError

log = logging.getLogger("line")

try:
    scanner = Scanner(license_key=os.environ["DOTCODE_LICENSE_KEY"])
except LicenseError as exc:
    # Expired, revoked or mistyped. Fail loudly at startup rather than
    # silently reading nothing all shift.
    log.critical("Cannot start: %s", exc)
    raise SystemExit(1)

camera = cv2.VideoCapture(0)

try:
    while True:
        ok, frame = camera.read()
        if not ok:
            continue

        result = scanner.decode(frame)          # no network, ~10-40 ms

        if result.ok:
            handle_pack(result.text)            # your business logic
        elif result.error.startswith("license_expired"):
            # Only after the year AND the 14-day grace have passed.
            log.error("Licence needs renewing -- contact voltionX")
            break
        # "no_dotcode_found" is normal: most frames have no code in them.
finally:
    camera.release()
    scanner.close()

7. Processing a folder of images

The other common shape: a folder of photographs from a line camera or a QA station, out to a CSV your systems already read.

batch.pyimport csv, os, pathlib
from dotcode_sdk import Scanner

scanner = Scanner(license_key=os.environ["DOTCODE_LICENSE_KEY"])
folder  = pathlib.Path("incoming")

with open("results.csv", "w", newline="") as fh:
    out = csv.DictWriter(fh, fieldnames=["file", "ok", "text",
                                         "gtin", "batch", "expiry", "ms"])
    out.writeheader()

    for image in sorted(folder.glob("*.png")):
        r = scanner.decode(str(image))
        out.writerow({
            "file":   image.name,
            "ok":     r.ok,
            "text":   r.text or "",
            # these are empty for a plain-text code, which is fine
            "gtin":   r.field("01") or "",
            "batch":  r.field("10") or "",
            "expiry": (r.gs1 or {}).get("fields", {}).get("17", ""),
            "ms":     round(r.elapsed_ms, 1),
        })

scanner.close()
print("done -> results.csv")

file,ok,text,gtin,batch,expiry,ms
pack_0001.png,True,010950110153000317250131...,09501101530003,ABC123,250131,14.2
pack_0002.png,False,,,,,8.1

When something fails

Every message you can see, what it means, and what to do.

Handling them in code

If your server uses a private certificate

The SDK reports two things back: which machine is running it, and how many scans it did. Neither affects decoding — but if it can't reach us, your dashboard shows no machines and no scans while the SDK works perfectly. The usual cause is a licence server on a private address with its own certificate.

You'll see this in your log the first time:

WARNING This machine could not register with the licence server --
        scanning works, but it will not appear in your dashboard.

Two ways to fix it:

To check from your own code:

scanner = Scanner(license_key=KEY)
import time; time.sleep(2)          # it registers in the background
print(scanner.cloud_ok)          # True, or False with the reason below
print(scanner.cloud_error)

Air-gapped sites

If the machine has no internet at all, turn the background calls off:

scanner = Scanner(license_key=KEY, telemetry=False)

Decoding is unaffected — it never used the network. You lose the usage charts in your portal, and we can't tell you a machine has gone quiet. The licence still expires on its own date.

Go-live checklist

• Key comes from an environment variable, not source control.
• The Scanner is created once at startup, not per frame.
• LicenseError at startup stops the service loudly.
• You have a calendar reminder ~30 days before the licence expires.
• You've checked the machine count in your portal matches how many you actually run.