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

# IoT

The Knowlix IoT module bridges your physical devices with your Knowlix workspace. Connect barcode scanners, receipt printers, label printers, payment terminals, cameras, scales, measurement instruments, customer displays, and foot pedals to extend system functionality into physical spaces like warehouses, manufacturing floors, and retail counters.

**Supported IoT system types:**

* **IoT Box** - a dedicated mini-computer with the Knowlix IoT software pre-installed, connects via Ethernet or Wi-Fi
* **Windows Virtual IoT** - the Knowlix IoT software installed on a Windows computer

> **Note:** Manufacturing devices including cameras and measurement tools are not compatible with Windows Virtual IoT.

An active IoT subscription is required for production use.

***

## IoT Box Setup

### Network Connection

**Ethernet (recommended):** Plug an Ethernet cable into the IoT box's network port and connect the other end to your router. Attach the power supply. All devices on the network must be on the same subnet: the IoT box, connected devices, and the computer running Knowlix.

**Wi-Fi:**

1. Connect the IoT box to power (no Ethernet cable attached).
2. On your computer, go to Wi-Fi settings and connect to the network named `IoTBox-xxxxxxxxxxxx`.
3. Your browser should automatically open the IoT box homepage. If not, navigate to `http://10.11.12.1`.
4. Click **Configure** next to Internet Status.
5. Select your Wi-Fi network, enter the password, and click **Connect**.

After connecting, the IoT box stops broadcasting its own Wi-Fi and your computer reconnects to its normal network.

> **Security:** Never expose the IoT box to the public internet. IoT systems are designed for local network use only.

### IoT Box Homepage

Access the homepage by opening a browser on the same network and navigating to the IoT box's IP address. Find the IP address by:

* Connecting the box to an external monitor (IP displays on screen)
* Connecting a supported receipt printer (IP prints automatically)
* Checking your router's connected device list

Once connected to your Knowlix workspace, access the homepage directly from **IoT module > IoT Boxes** by clicking the URL shown on the box's card.

***

## Windows Virtual IoT Setup

### Prerequisites

* Active IoT subscription
* Windows 10 or Windows 11 computer (laptop, desktop, or server)
* MRP devices (cameras, measurement tools) are NOT supported

### Installation

1. Download the Knowlix Community edition for Windows matching your database version.
2. Open the `.exe` file and allow system changes.
3. Select **Odoo IoT** from the install type dropdown. Required components: Odoo Server, Odoo IoT, Nginx WebServer, and Ghostscript.
4. Set the destination folder to `C:\odoo` (avoid user directories).
5. Complete the installation wizard including GPL Ghostscript setup.
6. The IoT homepage opens automatically at `http://localhost:8069`.

Verify access from another device on the same network by navigating to `http://[IoT-IP-address]:8069`.

### Windows Firewall Configuration

If other devices cannot reach the Windows virtual IoT, configure a firewall rule:

1. Open **Windows Defender Firewall with Advanced Security**.
2. Select **Inbound Rules** and click **New Rule**.
3. Select **Port** as the rule type.
4. Enter ports `8069, 80, 443` (add `9050` if using Worldline payment terminals).
5. Select **Allow the connection**.
6. Apply to relevant network profiles and give the rule a descriptive name.

### Windows Virtual IoT Management

**Restart the service:** Open Windows Services, find `odoo-server-xxx`, right-click and select **Restart**.

**Uninstall:** Use standard Windows program uninstallation. Confirm steps in the uninstall dialog.

***

## Connecting the IoT System to Knowlix

### Prerequisites

* IoT module installed in Knowlix
* IoT system connected to the network
* Computer accessing Knowlix on the same network as the IoT system
* Use a production Knowlix instance (staging environments may cause HTTPS certificate issues)

### Method 1: Pairing Code

The pairing code displays for up to 5 minutes after the IoT system starts.

**IoT Box:** Connect to an external monitor (code displays on screen) or printer (code prints automatically). Or access the IoT box homepage and look for the **Pairing Code** section.

**Windows Virtual IoT:** Open `http://localhost:8069` and scroll to the **Pairing Code** section.

Then in Knowlix:

1. Open the **IoT** module and click **Connect**.
2. Enter the pairing code in the dialog.
3. Click **Pair**.

If the pairing code has expired or is unavailable, reboot the IoT box or restart the Windows virtual IoT service to generate a new one.

### Method 2: Connection Token

1. In Knowlix, open the **IoT** module and click **Connect**.
2. Copy the **Token** shown in the dialog.
3. Open the IoT system's homepage.
4. Click **Configure** in the Knowlix database connected section.
5. Paste the token into the **Server Token** field and click **Connect**.

### IoT System Card

Once connected, the IoT system appears as a card in the IoT module. Click the IP address on the card to open its homepage. Click the card itself to view the list of connected devices.

Enable developer mode to see technical details including the system identifier, domain address, and image version.

By default, device drivers update automatically each time the IoT system restarts. Disable this in the **Technical Information** tab on the IoT system form if manual driver control is needed.

***

## Updating the IoT System

### IoT Box Image Update (Full Reinstall)

Required after upgrading your Knowlix database to a new major version.

1. Download and install balenaEtcher (or Raspberry Pi Imager).
2. Remove the micro SD card from the IoT box and insert it into your computer.
3. In balenaEtcher, click **Flash from URL** and enter the latest IoT box image URL.
4. Select the SD card as the target and click **Flash**.
5. Reinsert the SD card and power the IoT box.

### IoT Box Core Code Update

Access the IoT box homepage, click the **cogs** icon, then **Update**. Click **Update** under IoT Box Update.

> **Warning:** Do not power off the IoT box during a core update. The process can take over 30 minutes and interruption may require a full image reinstall.

### Windows Virtual IoT Update

Uninstall the current Windows virtual IoT program and reinstall the latest version.

### Driver Updates

To force a driver update without restarting:

1. Access the IoT system homepage and click the cogs icon.
2. Click **Update**, then **Force Drivers Update**.

***

## HTTPS Certificate

HTTPS is required for communication with payment terminals and some other network devices. The certificate is generated automatically when:

* The IoT system is connected to a production Knowlix instance
* An active IoT subscription is in place

When generated successfully, the IoT system homepage address updates to an HTTPS URL. The certificate validity period appears in the homepage cogs settings.

### Common Certificate Errors

| Error Code                                    | Cause                               | Resolution                                                        |
| --------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------- |
| ERR\_IOT\_HTTPS\_CHECK\_NO\_SERVER            | IoT not connected to Knowlix        | Connect the IoT system to your database                           |
| ERR\_IOT\_HTTPS\_CHECK\_CERT\_READ\_EXCEPTION | Certificate file unreadable         | Check file permissions on the IoT system                          |
| ERR\_IOT\_HTTPS\_LOAD\_NO\_CREDENTIAL         | Missing contract or database UUID   | Check credential settings via the cogs button on the IoT homepage |
| ERR\_IOT\_HTTPS\_LOAD\_REQUEST\_EXCEPTION     | Network/internet connectivity issue | Check firewall, VPN, and internet access                          |
| ERR\_IOT\_HTTPS\_LOAD\_REQUEST\_STATUS        | Unexpected HTTP response            | Check service status, open a support ticket with the status code  |
| ERR\_IOT\_HTTPS\_LOAD\_REQUEST\_NO\_RESULT    | Certificate refused by server       | Verify IoT subscription and production instance requirements      |

If the homepage opens via IP but not via the `.odoo-iot.com` URL, update DNS settings on affected devices to use a public DNS server (e.g., Google DNS `8.8.8.8`).

***

## Device Management

### Connecting Devices

**USB devices:** Plug the device into the IoT box or Windows virtual IoT computer. Compatible devices are detected automatically. Refresh the IoT system homepage to confirm the device appears.

**Bluetooth devices:** Activate Bluetooth on the device. The IoT system automatically discovers and connects to compatible devices.

### Printers

Supported printers connect via USB or network and appear automatically in the IoT Devices list (may take up to 2 minutes).

**Linking a printer to reports:**

1. Go to **IoT > Devices** and open the printer.
2. In the **Printer Reports** tab, click **Add a line** and select report types.

The first time a linked report is printed, a dialog prompts you to confirm the printer. The selection is saved per browser session.

**Common printer issues:**

* **Not detected:** Access the IoT system homepage, click **Show** in the Devices section to verify. Add the printer manually via Printer Server if needed.
* **Printing random characters:** Manually select the correct driver in the Printer Server settings (Printers > select printer > Administration > Modify Printer).
* **Appears multiple times:** The CUPS auto-discovery feature creates duplicate entries for each driver variant. Select the entry that works and ignore others.
* **Not recognized correctly:** Open the device in **IoT > Devices** and set the **Subtype** to Receipt Printer, Label Printer, or Office Printer.

**Epson printers using ESC \* mode:** Some older Epson models (TM-U220, TM-U230, TM-P60) do not support the standard GS v 0 command. For these, configure the printer name in CUPS using the convention `PrinterName__IMC_[params]__` (e.g., `EPSON_TM_U220__IMC_LDV_SCALE80__`) with appropriate density and scale parameters.

**DYMO LabelWriter:** Install the correct DYMO driver via Printer Server if labels print incorrectly. After updating the driver, add the printer again as a new entry to eliminate print delays.

### Barcode Scanners

Most scanners connect via USB and are detected automatically. Common issues:

* **Characters don't match the barcode:** Go to **IoT > Devices**, open the scanner, and set the correct **Keyboard Layout** for your region.
* **Nothing happens when scanning:** Verify the scanner is configured to send an ENTER character (keycode 28) after each barcode.
* **Detected as keyboard instead of scanner:** Open the device in **IoT > Devices** and enable **Is scanner**.
* **Characters scanned individually on mobile:** Set the correct keyboard layout in the device settings.

### Cameras

Connect cameras via USB cable. Compatible cameras are detected immediately.

**Linking a camera to a quality control point:**

1. Navigate to **Quality > Quality Control > Control Points**.
2. Open the control point and set the **Type** to **Take a Picture**.
3. Select the connected camera in the **Device** field.

When the control point is reached during manufacturing, the operator is prompted to take a photo.

**Linking a camera to a work center:**

1. Go to **Manufacturing > Configuration > Work Centers**.
2. Open the work center and add the camera in the **IoT Triggers** tab.
3. Set the **Action** to **Take a Picture** and optionally assign a keyboard trigger.

### Scales

Connect scales via USB (using a serial-to-USB adapter if needed). Compatible scales are auto-detected. If not detected, reboot the IoT system and update drivers.

After connection, configure the scale in POS settings.

**Mettler-Toledo Ariva S series:** Requires the official Mettler USB-to-RJ45 cable (part number 72256236) and specific scale firmware configuration. Set the USB communication mode to USB Virtual COM ports (option 1) and the protocol to Mettler-Toledo 8217 (option 3) in the scale's configuration menu.

### Measurement Tools

Connect measurement tools via USB or Bluetooth. Link them to quality control points by setting the control point **Type** to **Measure** and selecting the device.

Tolerance ranges and norm values can be configured on the control point. Measured values update automatically during production without manual entry.

### Customer Displays

Connect screens via HDMI (IoT Box model 3) or micro-HDMI (IoT Box model 4, supports two screens). Connect screens before powering the IoT box.

**Showing POS orders:**

1. Go to **Point of Sale > Configuration > POS settings**.
2. Enable **IoT Box** and select the screen in the **Customer Display** field.
3. The screen automatically updates as orders are modified.

**Displaying a website:** Open **IoT > Devices > Customer Display** and enter a URL in the **Display URL** field.

### Foot Pedals (Footswitches)

Connect footswitches via USB. Configure them on work centers:

1. Go to **Manufacturing > Configuration > Work Centers**.
2. Add the footswitch in the **IoT Triggers** tab.
3. Set the **Action** (e.g., Validate or Mark as Done) and an optional keyboard trigger.

### SSH Access to IoT Box

SSH connections are available for IoT boxes only (not Windows virtual IoT). Use this feature only with trusted technical personnel.

To enable SSH:

1. Open the IoT box homepage and click the cogs icon.
2. Click **Remote Debug**.
3. Click **Generate** and save the password immediately (it is not shown again after closing the dialog).
4. Enter the authentication token from the connecting user.
5. Click **Enable Remote Debugging**.

***

## Troubleshooting

| Problem                                               | Check                                                                     |
| ----------------------------------------------------- | ------------------------------------------------------------------------- |
| Pairing code not displayed                            | Internet connection, subscription status, code expiry (reboot to refresh) |
| IoT system connected but not visible in Knowlix       | Wait a few minutes, then reboot the IoT system                            |
| IoT box reachable but won't connect                   | Verify both are on the same network                                       |
| Windows virtual IoT not accessible from other devices | Configure Windows Firewall rule for ports 8069, 80, 443                   |
| IoT disconnects after Knowlix upgrade                 | Update IoT image to match the new Knowlix version                         |

***

## Best Practices

Use Ethernet instead of Wi-Fi for IoT boxes in high-availability environments. Always use production instances for IoT connections to ensure HTTPS certificate generation. Update IoT images after each major Knowlix upgrade. Test printer configurations with a print test page before deploying to production. Keep SSH remote debug disabled when not in active use.

**Your Knowlix:**
*"Show me all connected IoT devices"* or *"Which printers are linked to which reports?"* or *"Is the IoT box in the warehouse connected?"*