# Live data and status channel

Live data, status updates and actions

Only online noise instruments are supported through this API. If an instrument is online you can connect the websocket, if the instrument goes offline the websocket will be closed.

Requires an API key with the `instruments:read` scope to make the connection and begin receiving status updates. Other actions require additional scopes.

Method: CHANNEL
Version: 1.0.0
License: MIT

## Servers

### production
Production server
Host: api.mycirrus.cloud
Protocol: wss
Path: /v1

## Parameters

### instrument
The serial number of the instrument

## Messages

### LiveData

#### Payload Schema

- **type** (string)
  Type of message
  Enum: LiveData

- **time** (string)
  Time of the data

- **values** (array)
  List of live data values

- **name** (string)
  Name of the value

- **value** (number)
  The value in dB

### InstrumentStatus

#### Payload Schema

- **type** (string)
  Type of message
  Enum: InstrumentStatus

- **time** (string)
  Time of the status

- **online** (boolean)
  True if the instrument is online, otherwise false

- **measuring** (boolean)
  True if the instrument is measuring, otherwise false

- **calibrationInProgress** (boolean)
  True if the instrument is performing a calibration, otherwise false

- **sicInProgress** (boolean)
  True if the instrument is performing a System Integrity Check (SIC), otherwise false

### ActionStatus

#### Payload Schema

- **type** (string)
  Type of message
  Enum: ActionStatus

- **time** (string)
  Time of the status

- **action** (string)
  Action that was performed
  Enum: Identify, Calibration, SIC

- **status** (string)
  Status of the action
  Enum: InProgress, Success, Failed

- **error** (unknown)
  May contain additional error message if status is Failed

- **data** (unknown)

- **time** (string)
  Time of the calibration

- **status** (string)
  Status of the calibration

- **level** (number)
  The calibration level in dB

- **offset** (number)
  The offset from factory calibration in dB

- **time** (string)
  Time of the SIC result

- **status** (string)
  Status of the SIC

- **_500Hz** (number)
  The 500 Hz level in dB

- **_1KHz** (number)
  The 1 kHz level in dB

- **_8KHz** (number)
  The 8 kHz level in dB

### Error

#### Payload Schema

- **error** (string)
  Error code

- **description** (string)
  Description of the error

### KeepAlive
The connection will timeout after 1 minute of inactivity.<br>
To keep the connection alive, send a KeepAlive message every 30 seconds.

The server will respond with another KeepAlive message.

#### Payload Schema

- **action** (string)
  Action to perform
  Enum: KeepAlive

### DoAction
Perform an action on the instrument.

The possible actions are:
- Identify
  - The instrument will flash its LED.
- Calibration
  - The instrument will start the calibration process. You will need to attach an acoustic calibrator to the instrument.
- SIC
  - The instrument will perform a System Integrity Check (SIC).

&nbsp;

Requires an API key with the `instruments:action` scope.

#### Payload Schema

- **action** (string)
  Action to perform
  Enum: Identify, Calibration, SIC

### StartStopLiveData
Start or stop live data.

If you specify the `StartLiveData` action the server will start sending live data for the specified types.<br>
If the server is already sending live data, the types will be updated.

If you specify the `StopLiveData` action the server will stop sending live data.

The possible live data types are:
- Leq
  - LAeq, LCeq, LZeq, LAeqI
  - LAeqT
- Peak
  - LAPeak, LCPeak, LZPeak
- SPL
  - LAF, LAS, LAI
  - LCF, LCS, LCI
  - LZF, LZS, LZI
- Statistical Levels
  -  Ln1, Ln5, Ln10, Ln50, Ln90, Ln95, Ln99
- Moving Average
  - Examples: LAeq,5m, LAeq,60m
  - _Available values dependant on settings_
- Octaves
  - 31.5Hz, 63Hz, 125Hz, 250Hz, 500Hz, 1KHz, 2KHz, 4KHz, 8KHz, 16KHz
- Third Octaves
  - 6.3Hz3 to 20KHz3
  - _Names end with 3 to differentiate from octave bands_

&nbsp;

Some types may be unavailable depending on subscription plan.<br>
If you specify an invalid or unavailable type, the server will ignore it.<br>
If all specified types are invalid or no types are specified, the server will respond with an error.

Requires an API key with the `data.live:read` scope.

#### Payload Schema

- **action** (string)
  Action to perform
  Enum: StartLiveData, StopLiveData

- **types** (array)
  List of requested live data types