---
sidebar_position: 0
---

# hardware

The `sos.hardware` API groups together methods for working with hardware. It allows opening serial ports, using bar scanner or controlling LEDs.

:::warning
- Before using this API, ensure that the display [supports](/sdk/sos/display#supports) serial via `sos.display.supports("SERIAL")`.
- Samsung Kiosk serial connection only works over serial ports, not over USB ports.
:::

<details>
    <summary>Device Hardware Capabilities</summary>
		| Capability | Description |
		|:------------|:-------------|
		| `SERIAL` | If the device supports sending and receiving data via serial ports |

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

### List of supported serial ports
Bellow is example list of serial ports that can be used with `sos.hardware.openSerialPort()` method.

| Device type | Default value | Other available values |
|:----|:-----|:------|
| RaspberryPi / Linux | `/dev/ttyS0` | `/dev/ttyS1`, `/dev/ttyUSB0`, `/dev/ttyUSB1` |
| Windows | `COM3` | `COM1`, `COM2`, `COM4` etc. Usually it's always `COM3` |
| Samsung Kiosk | `PORT1` | `PORT2`, `PORT3`, `PORT4` |
| Android | `/dev/ttyusb0` | `/dev/ttyusb1`, `/dev/ttyusb2` |
| BrightSign | `0` | `0` (Serial Jack as `/dev/ttyS0`), `1` (GPIO port as `/dev/ttyS1`), `USB:A/0` (USB-to-serial as `/dev/ttyUSB0`) |

## Methods

### openSerialPort()

The `openSerialPort()` method opens a serial port for reading/writing. After the port is opened the method returns 

```ts expandable
openSerialPort(options: ISerialPortOptions): Promise<ISerialPort>;
// show-more
/**
 * Options for opening a serial port used by the `sos.hardware.openSerialPort()` method.
 *
 * @remarks
 * All properties are optional except `baudRate`.
 */
interface ISerialPortOptions {
    device?: string;
    baudRate: number;
    parity?: Parity;
    databits?: number;
    stopbits?: number;
    rtscts?: boolean;
}

enum Parity {
    NONE = "none",
    EVEN = "even",
    MARK = "mark",
    ODD = "odd",
    SPACE = "space"
}

/**
 * Returned by sos.hardware.openSerialPort() method.
 * This interface provides methods to read/write data from/to the serial port.
 */
interface ISerialPort {
    /**
     * The `onData()` method sets up a listener, which is called whenever new data are received. The listener will stop after the serial port
     * is closed.
     *
     * @param listener A function that will be called with the received data as a Uint8Array.
     * @returns {void} Returns when the listener is set up.
     */
    onData(listener: (data: Uint8Array) => void): void;
    /**
     * The `write()` method writes data to the serial port. The data can be a string of hexadecimal digits, array of numbers or Uint8Array.
     *
     * @param data The data to write to the serial port.
     * @returns {Promise<void>} Returns a promise that resolves when the data is successfully written to the serial port.
     * @throws {Error} If the data cannot be written to the serial port.
     * @throws {Error} If the serial port is not open.
     * @throws {Error} If any other error occurs while writing to the serial port.
     *
     * @example
     * // serial port instance previously created via sos.hardware.openSerialPort()
     * await serialPort.write('68656c6c6f'); // hexadecimal string
     * await serialPort.write([ 10, 20, 30, 40 ]); // array of numbers
     * await serialPort.write(Uint8Array.from([ 10, 20, 30, 40 ])); // Uint8Array
     */
    write(data: string | number[] | Uint8Array): Promise<void>;
    /**
     * The `close()` method closes the serial port.
     *
     * @returns {Promise<void>} Returns a promise that resolves when the serial port is successfully closed.
     * @throws {Error} If the serial port cannot be closed.
     */
    close(): Promise<void>;
}

```

#### Params

| Name               | Type      | Required         | Description                                                                                                         |
|--------------------|-----------|------------------|---------------------------------------------------------------------------------------------------------------------|
| `options.device`   | `string`  |  <div>No</div>   | Specifies the address of the external device, check the table above for ports.                                      |
| `options.baudRate` | `number`  |  <div>Yes</div>  | Specifies the data transmission speed in bits per second.                                                           |
| `options.parity`   | `Parity`  |  <div>No</div>   | Specifies the form of error checking, whether (or what) extra bits are added to a byte.                             |
| `options.databits` | `number`  |  <div>No</div>   | Specifies the number of bits in a byte.                                                                             |
| `options.stopbits` | `number`  |  <div>No</div>   | Specifies the number of bits used to signal the end of a communication packet.                                      |
| `options.rtscts`   | `boolean` |  <div>No</div>   | Enables or disables RTS/CTS handshaking over the serial port. Currently supported by selected models of BrightSign. |

#### Return value

Returns a promise that resolves to an instance of 

#### Possible errors


- If the serial port cannot be opened.
- If the device address is not supported by the platform.
- If the device fails to process the data.
- If any other error occurs while opening the serial port.

#### Example

```ts
// Open serial port on BrightSign with default settings
const serialPort = await sos.hardware.openSerialPort({
	device: '0',
	baudRate: 9600,
});
serialPort.write('68656c6c6f'); // Write "hello" in hexadecimal
```

## API Example

```ts
import { sos } from '@signageos/front-applet';

void sos.onReady(async () => {
	// Open default serial port based platform
	const serialPort = await sos.hardware.openSerialPort({
		baudRate: 115200,
	});

	await serialPort.close();
});

void sos.onReady(async () => {
	// Open specific serial port
	const serialPort = await sos.hardware.openSerialPort({
		device: '/dev/ttyUSB0',
		baudRate: 115200,
	});

	serialPort.onData((data) => {
		const dataString = [...data].map((char) => String.fromCharCode(char)).join('');
		console.log(dataString);
	});

	await serialPort.write('68656c6c6f'); // hexadecimal string
	await serialPort.write([10, 20, 30, 40]); // array of numbers
	await serialPort.write(Uint8Array.from([10, 20, 30, 40])); // Uint8Array

	await serialPort.close();
});

```