> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Barcode Connector

> Decode barcode images from MQTT and encode text as PNG or PDF symbols with TYPE BARCODE

## Read and draw barcodes on MQTT

The Barcode connector turns an image on a topic into the text inside the symbol, or turns text into a PNG or PDF you can display and print. Point a camera connector at the decode event when the image is already a frame on MQTT.

> [!TIP]
>
> **Like a checkout scanner.** You show it a picture of the code (decode), or you hand it the product number and it prints the label (encode).

### When to use this

Use `TYPE BARCODE` when a camera, file, or upstream system already has the image, or when you need to generate a QR, retail, or 2D symbol from text. Limit `SUPPORTED_FORMATS` to the families you actually scan so detection stays fast.

***

Each tab below is a complete connector. Publish an image to the decode topic, or a JSON request to the encode topic.

## Quick Start

**Decode an image**

Read a symbol from a base64 image and publish JSON, plus an annotated copy of the frame:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE BarcodeScanner WITH TYPE BARCODE
    ADD BARCODE_CONFIG
        WITH SUPPORTED_FORMATS "QR_CODE,CODE_128,EAN_13,UPC_A"
    ADD EVENT ScanBarcode
        WITH MODE "DECODE"
        WITH SOURCE_TOPIC "camera/frame"
        WITH DESTINATION_TOPIC "barcode/decoded"
        WITH ANNOTATED_IMAGE_TOPIC "barcode/annotated"
        WITH ENABLE_ANNOTATION "true"
        WITH ANNOTATION_COLOR "Blue"
        WITH ANNOTATION_THICKNESS "3"
```

**Encode a symbol**

Generate a PNG from a JSON request on `barcode/generate`:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE BarcodeGenerator WITH TYPE BARCODE
    ADD BARCODE_CONFIG
        WITH SUPPORTED_FORMATS "QR_CODE,CODE_128"
    ADD EVENT GenerateBarcode
        WITH MODE "ENCODE"
        WITH SOURCE_TOPIC "barcode/generate"
        WITH DESTINATION_TOPIC "barcode/image"
```

**Line scanner**

Decode two cameras on one connector, and annotate only the serial camera:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE ProductionScanner WITH TYPE BARCODE
    ADD BARCODE_CONFIG
        WITH SUPPORTED_FORMATS "CODE_128,DATA_MATRIX"
    ADD EVENT ScanProduct
        WITH MODE "DECODE"
        WITH SOURCE_TOPIC "line/camera/frame"
        WITH DESTINATION_TOPIC "line/product/scanned"
    ADD EVENT ScanSerial
        WITH MODE "DECODE"
        WITH SOURCE_TOPIC "line/serial/frame"
        WITH DESTINATION_TOPIC "line/serial/decoded"
        WITH ENABLE_ANNOTATION "true"
        WITH ANNOTATED_IMAGE_TOPIC "line/serial/annotated"
```

***

## Configuration

**SUPPORTED\_FORMATS** `string`

Comma-separated format names. Omit it to allow every format in the table below. Names are uppercase (`QR_CODE`, not `qr_code`).

### Supported formats

| Format | Kind |
| - | - |
| `QR_CODE` | 2D |
| `CODE_128` | 1D |
| `CODE_39` | 1D |
| `EAN_13` | 1D retail |
| `EAN_8` | 1D retail |
| `UPC_A` | 1D retail |
| `UPC_E` | 1D retail |
| `PDF_417` | 2D stacked |
| `DATA_MATRIX` | 2D |
| `AZTEC` | 2D |
| `ITF` | 1D |
| `MSI` | 1D |
| `PLESSEY` | 1D |
| `CODABAR` | 1D |
| `RSS_14` | 1D |
| `RSS_EXPANDED` | 1D |
| `MAXICODE` | 2D |

## Events

Every event sets `MODE` to `DECODE` or `ENCODE`.

**MODE** `string` *required*

`DECODE` reads a symbol from an image. `ENCODE` draws a symbol from JSON.

**SOURCE\_TOPIC** `string` *required*

Topic that triggers the event. Decode expects an image. Encode expects JSON.

**DESTINATION\_TOPIC** `string` *required*

Topic for the JSON result.

### Decode

Publish the image as a raw base64 string. A data-URI prefix such as `data:image/jpeg;base64,` is accepted. A [Video Input](./video-input) frame is already in that form, so you can set the decode `SOURCE_TOPIC` to the camera's frame topic.

> **Annotation**
>
> **ENABLE\_ANNOTATION** `string`
>
> `true` or `false`. Default: `true`. Draws a box around the symbol that was read.
>
> **ANNOTATED\_IMAGE\_TOPIC** `string`
>
> Topic for the annotated image. The payload is a raw base64 string, same shape as the input image.
>
> **ANNOTATION\_COLOR** `string`
>
> Color name, for example `Red` or `Blue`. Default: `Red`.
>
> **ANNOTATION\_THICKNESS** `string`
>
> Line thickness as an integer. Default: `5`.

A successful decode publishes JSON like this:

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "text": "Decoded barcode text",
  "format": "QR_CODE",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "route_name": "BarcodeScanner",
  "event_name": "ScanBarcode"
}
```

When no symbol is found, `success` is `false` and `error` explains why (for example `No barcode found in image`). Check `success` before you trust `text`.

Large frames are scaled down before detection. If a sharp 1080p frame still fails, publish a 1280×720 or 640×480 image instead.

### Encode

Publish JSON on the encode `SOURCE_TOPIC`. `text` is the payload to draw. `format` must be one of the names in `SUPPORTED_FORMATS`.

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "text": "Product-12345",
  "format": "QR_CODE",
  "width": 300,
  "height": 300,
  "margin": 0,
  "output_type": "IMAGE"
}
```

| Field | Default | Role |
| - | - | - |
| `text` | — | Content to encode |
| `format` | — | Symbol family, uppercase |
| `width` / `height` | — | Pixel size of the symbol |
| `margin` | `0` | Quiet zone around the symbol |
| `output_type` | `IMAGE` | `IMAGE` (PNG data-URI) or `PDF` |

An image result includes `image_base64` (`data:image/png;base64,…`). A PDF result includes `pdf_base64` (`data:application/pdf;base64,…`). Both include `success`, `text`, `format`, `output_type`, `width`, `height`, `timestamp`, `route_name`, and `event_name`.

> **PDF page placement**
>
> Set `output_type` to `PDF` and add `pdf_options`. Units are points (A4 is 595 × 842).
>
> | Field | Default | Role |
> | - | - | - |
> | `page_width` | `595` | Page width |
> | `page_height` | `842` | Page height |
> | `x_position` | `50` | Left edge of the symbol |
> | `y_position` | `750` | Baseline position on the page |
> | `include_text` | `true` | Print the encoded text on the page |
> | `text_below` | `true` | Place that text under the symbol |
> | `font_size` | `12` | Text size |
>
> ```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> {
>   "text": "1234567890123",
>   "format": "EAN_13",
>   "width": 300,
>   "height": 100,
>   "output_type": "PDF",
>   "pdf_options": {
>     "page_width": 595,
>     "page_height": 842,
>     "x_position": 50,
>     "y_position": 750,
>     "include_text": true,
>     "text_below": true,
>     "font_size": 12
>   }
> }
> ```

## Trigger from an action

Publish the image or the encode JSON straight to `SOURCE_TOPIC`, or hand the payload to a named event:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DecodeBarcodeFromImage
ON TOPIC "camera/capture" DO
    TRIGGER "BarcodeScanner" TO PAYLOAD FOR "ScanBarcode"
```

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION GenerateQRCode
ON TOPIC "qr/generate" DO
    SET "data" WITH CLEAN:{text: {value.json.text}, format: "QR_CODE", width: 300, height: 300, output_type: "IMAGE"}
    TRIGGER "BarcodeGenerator" TO {data} FOR "GenerateBarcode"
```

## Best Practices

> **Image quality**
>
> Use a sharp, evenly lit frame. Blur and glare are the usual reason decode returns `No barcode found in image`. For retail codes, 640×480 to 1280×720 is enough.

> **Format selection**
>
> QR for URLs and mixed content. EAN-13 and UPC-A for retail. Code 128 for alphanumeric IDs. List only those names in `SUPPORTED_FORMATS`.

> **Errors**
>
> Branch on `success`. A `false` result still arrives on `DESTINATION_TOPIC`, so a downstream action should not treat every message as a good scan.

## Troubleshooting

> **No barcode found in image**
>
> Confirm the symbol is in frame and the format name is listed in `SUPPORTED_FORMATS`. Retry with a smaller, sharper image.

> **Invalid barcode format**
>
> Use the uppercase names from the format table, spelled exactly, and include that name in `SUPPORTED_FORMATS`.

> **Base64 decode error**
>
> The payload must be the base64 image, with or without a `data:image/…;base64,` prefix, and with no extra characters around it.

## Next Steps

> **[Video Input](./video-input)**
>
> Publish camera frames, then point a decode event at that topic.

> **[Media Connectors](./overview)**
>
> Choose barcode, video, or audio.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.