---
sidebar_position: 0
---

# barcodeScanner

The `sos.hardware.barcodeScanner` API provides methods for working with barcode scanners.
It allows starting and stopping the scanner, as well as listening for scanned data and errors.

:::note
This API is experimental and may change in the future.
:::

<details>
    <summary>Device Barcode Scanner Capabilities</summary>
		| Capability | Description |
		|:------------|:-------------|
		| `BARCODE_SCANNER` | If device supports serial communication for Barcode Scanners |

		If you want to check if the device supports this capability, use [`sos.display.supports()`](https://developers.signageos.io/sdk/sos/display#supports).
</details>

## Methods

### getVersion()

The `getVersion()` method returns the version of the barcode scanner.

```ts expandable
getVersion(): Promise<string>;
```

#### Return value

Returns a promise that resolves to the version of the barcode scanner.

#### Possible errors

If the version cannot be retrieved.

<Separator />

### start()

The `start()` starts the barcode scanner and starts listening for scanned data.

```ts expandable
start(userOptions?: Omit<IBarcodeScannerOptions, 'scannerId'>): Promise<IBarcodeScannerResponse>;
// show-more
interface IBarcodeScannerOptions {
    timeout?: number;
    cancelPrevious?: boolean;
    scannerId?: number;
}

interface IBarcodeScannerResponse {
    stop: () => Promise<void>;
    onData: (listener: (data: string) => void) => void;
    onError: (listener: (error: Error) => void) => void;
}

```

#### Params

| Name                         | Type                                        | Required        | Description                                                                               |
|------------------------------|---------------------------------------------|-----------------|-------------------------------------------------------------------------------------------|
| `userOptions`                | `Omit<IBarcodeScannerOptions, "scannerId">` |  <div>No</div>  | User options to configure the scanner.                                                    |
| `userOptions.timeout`        | `number \| undefined`                       |  <div>No</div>  | The maximum time to wait for a scan before timing out.                                    |
| `userOptions.cancelPrevious` | `boolean \| undefined`                      |  <div>No</div>  | If set to `true`, it will cancel any previous scanner instance with the same `scannerId`. |

#### Return value

Returns a promise that resolves to an object with methods to stop the scanner and listen for scanned data and errors.

#### Possible errors


- If the scanner cannot be started.
- If the scanner is already running and `cancelPrevious` option is not set to `true`.
- If any other error occurs while starting the scanner.

#### Example

```ts
// Start the barcode scanner with default options
const scanner = await sos.hardware.barcodeScanner.start();
// Listen for scanned data
scanner.onData((data) => {
	console.log(`Scanned data: ${data}`);
});
// Listen for errors
scanner.onError((error) => {
	console.error(`Scanner error: ${error.message}`);
});
```