---
sidebar_position: 0
---

# command

In some cases, you might be interested in a complete log of what the device was doing during its operation. All of your business or technical logs can be stored in our storage for later usage. You can identify which events happened or even trigger self-repairing logic.

All commands will be available in [Applet Command REST API](https://developers.signageos.io/api/#tag/DeviceApplet-Command) and can be downloaded historically as [CSV export](https://developers.signageos.io/api/#tag/DeviceMonitoring/paths/~1v1~1device~1%7BdeviceUid%7D~1report/get).

## Methods

### dispatch()

The `dispatch()` method dispatches a new log record to the signageOS.

:::warning[Dispatch throttling]
Sending commands from an applet is throttled, this means that after if the dispatch frequency is too high, some commands may be
discarded. Currently, the limit is 30 commands per 30 seconds, although this may not be fully accurate, and it's not possible to know the
exact limit.
:::

```ts expandable
dispatch<TCommand extends ICommand>(command: TCommand): Promise<void>;
// show-more
/**
 * Interface represents a command structure with a type and additional data.
 */
interface ICommand {
    type: string;
    /**
     * The `data` property is an object that contains additional data related to the command.
     */
    [key: string]: any;
}

```

#### Params

| Name      | Type       | Required         | Description                   |
|-----------|------------|------------------|-------------------------------|
| `command` | `TCommand` |  <div>Yes</div>  | The command to be dispatched. |

#### Possible errors


- If type contains invalid characters, allowed to are `/^[a-zA-Z0-9\.\-_]+$/g`
- If the command type is longer then 100 characters limit.
- If the command is not an object or is missing required properties.

#### Example

```ts
await sos.command.dispatch({
  type: 'Files.StartLoading',
  fileName: 'my-file',
  fileType: 'txt'
});
```

:::note[GitHub Example]

- [ Sending commands in Applet](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/sending/)
- [ Rest API - Dispatching commands](https://developers.signageos.io/api/#tag/DeviceApplet-Command/paths/~1v1~1device~1%7BdeviceUid%7D~1applet~1%7BappletUid%7D~1command/post)
- [ Rest API - Get commands](https://developers.signageos.io/api/#tag/DeviceApplet-Command/paths/~1v1~1device~1%7BdeviceUid%7D~1applet~1command/get)
- [ Rest API - Receiving historical data](https://developers.signageos.io/api/#tag/DeviceMonitoring/paths/~1v1~1device~1%7BdeviceUid%7D~1report/get)

:::

<Separator />

### onCommand()

The `onCommand()` method sets up a listener, which is called whenever a new command from signageOS is received.

```ts expandable
onCommand(listener: (command: ICommandEvent) => void): void;
// show-more
/**
 * Received command event interface from signageOS.
 */
interface ICommandEvent {
    type: 'command';
    /**
     * Command data received from occurred event.
     */
    command: ICommand;
}

/**
 * Interface represents a command structure with a type and additional data.
 */
interface ICommand {
    type: string;
    /**
     * The `data` property is an object that contains additional data related to the command.
     */
    [key: string]: any;
}

```

#### Params

| Name       | Type                               | Required         | Description                                               |
|------------|------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(command: ICommandEvent) => void` |  <div>Yes</div>  | The listener to be called when a new command is received. |

#### Return value

Resolves when the listener is successfully set up.

:::note[GitHub Example]

- [ Receiving commands in Applet](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/command/receiving)

:::

## API Example

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

void sos.onReady(async () => {
	/* Example of dispatching information about file download */
	await sos.command.dispatch({
		type: 'Files.StartLoading', // mandatory *type* with custom value
		fileName: 'my-file', // custom parameter and value
		fileType: 'txt', // custom parameter and value
	});

	sos.command.onCommand((command) => {
		console.log(`new command ${command.type} received, with data:`, command.command);
	});
});

```