idun_guardian_sdk

class idun_guardian_sdk.GuardianClient(address=None, ws_endpoint_url=None, http_endpoint_url=None, api_token=None, debug=False)

Main Class object for the user to interact with IDUN Guardian Earbuds and APIs

All functional operations can be done through this class object: Device (Bluetooth) Operations, HTTP API, and Live Recording.

Parameters:

  • address (str, optional) – The MAC address of the Guardian Earbuds.

  • ws_endpoint_url (str, optional) – The WebSocket endpoint URL. If not provided, the default URL is used.

  • http_endpoint_url (str, optional) – The HTTP endpoint URL. If not provided, the default URL is used.

  • api_token (str, optional) – The API token. Defaults to None. Required if any API call is needed.

  • debug (bool, optional) – Enable debug mode. Defaults to False.

async check_battery()

Reads and print the battery level of the device

async connect_device()

Bluetooth connect to the Guardian Earbuds device

Device connection is automatically handled by the SDK. You can call this method to connect to the device as needed.

delete_recording(recording_id)

Deletes a recording from the Guardian HTTP API.

Parameters:

recording_id (str) – The ID of the recording to delete.

async disconnect_device()

Bluetooth disconnect the Guardian Earbuds device

Device disconnection is automatically handled by the SDK on program exit. You can call this method to disconnect to the device as needed.

download_daytime_report_raw_data(recording_id, file_path=None)

Downloads the daytime report raw data for a recording.

Parameters:

  • recording_id (str) – The ID of the recording to download the daytime report raw data.

  • file_path (str | None)

download_file(recording_id, file_type, file_path=None)

Download a file from a recording. Possible file types are: EEG, IMU, IMPEDANCE

Parameters:

  • recording_id (str) – the id of the recording

  • file_type (FileTypes) – the type of file to download

  • file_path (str, optional) – where to save the file

download_sleep_report_raw_data(recording_id, file_path=None)

Downloads the sleep report raw data for a recording.

Parameters:

  • recording_id (str) – The ID of the recording to download the sleep report raw data.

  • file_path (str | None)

end_recording(recording_id)

Ends a recording from the Guardian HTTP API.

Parameters:

recording_id (str) – The ID of the recording to end.

generate_and_download_daytime_report(recording_id, file_path=None)

Generates and downloads a daytime report for a recording from the Guardian HTTP API.

Parameters:

  • recording_id (str) – The ID of the recording to generate the daytime report for.

  • file_path (str, optional) – The path to save the daytime report to. Defaults to None.

generate_and_download_sleep_report(recording_id, file_path=None)

Generates and downloads a sleep report for a recording from the Guardian HTTP API.

Parameters:

  • recording_id (str) – The ID of the recording to generate the sleep report for.

  • file_path (str, optional) – The path to save the sleep report to. Defaults to None.

async get_device_mac_address()

Get the MAC address of the Guardian Earbuds. It searches the MAC address of the device automatically. This address is used as the deviceID for cloud communication

Return type:

str

get_recording_id()

Gets the ID of current recording.

Raises: ValueError: If the recording ID is not available

get_recordings(limit=200, status=None, page_index=None)

Retrieves recordings from the Guardian HTTP API.

Parameters:

  • limit (int, optional) – The maximum number of recordings to retrieve. Defaults to 200.

  • status (str, optional) – The status of the recordings to retrieve. Defaults to None. Status options are: - NOT_STARTED - Status for a recording when a “start recording” signal is sent, but no data has been sent yet. - ONGOING - This is the state of a recording when the data are still incoming. - PROCESSING - When the API receives a “stop recording signal”, the recording status is set to processing. - COMPLETED - When the recording has been successfully finished and saved. - FAILED - If the recording failed.

  • page_index (int, optional) – The index of the page to retrieve. Defaults to None.

Returns:

A list of recordings retrieved from the Guardian HTTP API.

Return type:

list

get_user_info()

Get the user information from the Guardian HTTP API, depending on the API token provided.

Returns:

A dictionary containing the following keys:

  • ’idun_id’: The IDUN ID of the user.

  • ’device_id’: The device ID of the user.

Return type:

dict

async search_device()

Search for the Guardian Earbuds device and return the address

Returns:

Address of the device

Return type:

str

async start_recording(recording_timer=36000, led_sleep=False, calc_latency=False)

Start recording data from the Guardian Earbuds. Bidirectional websocket connection to the Guardian Cloud API. The recording keeps running until the recording_timer is reached or the user manually stops the recording by gracefully interrupting the recording with Ctrl + C

Parameters:

  • recording_timer (int, optional) – The duration of the recording in seconds. Defaults to 36000.

  • led_sleep (bool, optional) – Enable LED sleep mode. Defaults to False.

  • calc_latency (bool) – Enables calculation and printing data transmission latency to the cloud. Defaults to False.

Returns:

Recording ID

Return type:

str

Raises:

ValueError – For wrong Device ID

stop_impedance()

Stops impedance streaming

async stream_impedance(mains_freq_60hz=False, handler=None)

Stream impedance data from the Guardian Earbuds

Parameters:

  • mains_freq_60hz (bool, optional) – Set to True if the mains frequency is 60Hz. Defaults to False.

  • handler (callable, optional) – The callback function to handle the impedance data

subscribe_live_insights(raw_eeg=False, filtered_eeg=False, imu=False, handler=<function default_console_handler>)

Subscribe for live insights from the Guardian Earbuds. One of the optional flags must be set to True.

Parameters:

  • raw_eeg (bool, optional) – Subscribe for Raw EEG data. Defaults to False.

  • filtered_eeg (bool, optional) – Subscribe for Filtered EEG data. Defaults to False.

  • imu (bool, optional) – Subscribe for IMU data. Defaults to False.

  • handler (callable) – The callback function to handle the live insights data

Raises:

ValueError – If none of the optional flags are set to True

subscribe_realtime_predictions(fft=False, jaw_clench=False, bin_heog=False, handler=<function default_console_handler>)

Subscribe for real-time predictions from the Guardian Earbuds. One of the optional flags must be set to True.

Parameters:

  • fft (bool, optional) – Subscribe for FFT data. Defaults to False.

  • jaw_clench (bool, optional) – Subscribe for Jaw Clench data. Defaults to False.

  • bin_heog (bool, optional) – Subscribe for BIN_HEOG data. Defaults to False.

  • handler (callable) – The callback function to handle the real-time predictions data

Raises:

ValueError – If none of the optional flags are set to True

update_recording_display_name(recording_id, display_name)

Updates the display name of a recording from the Guardian HTTP API.

Parameters:

  • recording_id (str) – The ID of the recording to update.

  • display_name (str) – The new display name.

update_recording_tags(recording_id, tags)

Updates the tags of a recording from the Guardian HTTP API.

Parameters:

  • recording_id (str) – The ID of the recording to update.

  • tags (list) – The list of tags to update.

property api_token

Lazy loading of the API token

property guardian_ble

Lazy loading of the GuardianBLE object

property guardian_http_api

Lazy loading of the GuardianHttpAPI object

property guardian_recording

Lazy loading of the GuardianRecording object

class idun_guardian_sdk.GuardianHttpAPI(url, api_token)

Class that encapsulates the HTTP API calls to the Idun Guardian API.

Parameters:

  • url (str) – the base URL of the API

  • api_token (str) – the API token to authenticate the requests

delete_recording(recording_id)

Completely deletes a recording.

Parameters:

recording_id (str) – The id of the recording to be deleted

download_daytime_report(recording_id)

Downloads the daytime report for a recording.

Parameters:

recording_id (str) – The id of the recording. The report must be generated first.

Returns:

object containing the status and the presigned signed URL to download the file

Return type:

ReportResponse

Raises:

APIRequestError – If the request or the report download fails

download_daytime_report_raw_data(recording_id)

Downloads the daytime report raw data for a recording.

Parameters:

recording_id (str) – The id of the recording. The report must be generated first.

Return type:

ReportResponse

download_recording(recording_id, file_type)

Downloads the recording data file.

Parameters:

  • recording_id (str) – the id of the recording. Must be a COMPLETED recording.

  • file_type (idun_guardian_sdk.FileTypes) – possible values: EGG, IMU, IMPEDANCE

Returns:

The presigned signed URL to download the file

Return type:

str

download_sleep_report(recording_id)

Downloads the sleep report for a recording.

Parameters:

recording_id (str) – The id of the recording. The report must be generated first.

Returns:

object containing the status and the presigned signed URL to download the file

Return type:

ReportResponse

Raises:

APIRequestError – If the request or the report download fails

download_sleep_report_raw_data(recording_id)

Downloads the sleep report raw data for a recording.

Parameters:

recording_id (str) – The id of the recording. The report must be generated first.

Return type:

ReportResponse

end_recording(recording_id)

Send end signal to a recording.

Parameters:

recording_id (str) – The id of the recording.

generate_daytime_report(recording_id)

Send signal to the API to generate the daytime report for a recording.

Parameters:

recording_id (str) – The id of the recording. Must be a COMPLETED recording.

Raises:

APIRequestError – If the request or the report generation fails

generate_sleep_report(recording_id)

Sends signal to the API to generate the sleep report for a recording.

Parameters:

recording_id (str) – The id of the recording. Must be a COMPLETED recording.

Raises:

APIRequestError – If the request or the report generation fails

get_recordings(limit=200, status=None, page_index=None)

Returns all the recordings. You can filter by status and limit the number of results.

Parameters:

  • limit (int) – how many recordings to download. Default is 200

  • status (str, optional) – the status of the recording. Possible values: NOT_STARTED, ONGOING, PROCESSING, COMPLETED, FAILED

  • page_index (int, optional) – used in case of paginating the results. Pass the lastEvaluatedKey from the previous response

Returns:

the result of the query. All the recordings and the lastEvaluatedKey for pagination.

If lastEvaluatedKey is None, there are no more results

Return type:

dict

get_user_info()

Get the user information.

Returns:

the user information with the idun_id and the device_id keys

Return type:

dict

save_file_from_s3(url, file_path)

Saves a file from an S3 presigned URL to the local file system.

Parameters:

  • url (str) – the presigned URL to download the file

  • file_path (str) – the path where to save the file. If None, the file is saved in the current directory

Returns:

the full path of the saved file

Return type:

str

Raises:

ValueError – If the URL is not valid

update_recording_display_name(recording_id, display_name)

Updates the display name of a recording.

Parameters:

  • recording_id (str) – The id of the recording.

  • display_name (str) – The new display name.

update_recording_tags(recording_id, tags)

Updates the tags of a recording.

Parameters:

  • recording_id (str) – The id of the recording.

  • tags (list) – The tags to update.

class idun_guardian_sdk.GuardianRecording(ws_url, api_token)

Main Guardian API client.

Initialize Guardian API client.

Parameters:

  • debug (bool, optional) – Enable debug logging. Defaults to True.

  • ws_url (str)

  • api_token (str)

set_init_recording()

Set/Reset initial recording properties.

async start_streaming(calc_latency=False)

Connect to the Guardian API websocket.

Parameters:

calc_latency (bool) – Enables calculation and display of data transmission latency to the cloud. Defaults to False.

Raises:

Exception – If the websocket connection fails

Return type:

None

class idun_guardian_sdk.GuardianBLE(address='')

Main Guardian BLE client.

Initialize the Guardian BLE client.

Parameters:

address (str, optional) – BLE device address. Defaults to “”.

async connect_device()

Connects the device

Sets the connect_ble flag to True and waits for the connection to be established by the connection handler

Do nothing if the device is already connected

async connect_to_device()

This function initialises the connection to the device. It finds the device using the address, sets up callback, and connects to the device.

async disconnect_device()

Disconnects the device

Sets the connect_ble flag to False and waits for the connection to be established by the connection handler

Do nothing if the device is already disconnected

async get_device_mac()

Get the device MAC address. Device must be already connected This is different from BLE device address (UUID on Mac or MAC address on Windows)

Returns:

MAC address

Return type:

str

async read_battery_level()

Read the battery level of the device given pre-defined interval.

Return type:

None

async run_ble_record(guardian_recording, record_time=60, led_sleep=False)

This function runs the recording of the data. It sets up the bluetooth connection, starts the recording, and then reads the data and adds it to the queue. The API class then reads the data from the queue and sends it to the cloud.

Parameters:

  • guardian_recording (GuardianRecording) – GuardianRecording object

  • record_time (_type_) – The time to record for

  • led_sleep (_type_) – Whether to turn off the LED

Raises:

BleakError – _description_

Return type:

None

async static search_device()

This function searches for the device and returns the address of the device. If the device is not found, it exits the program. If multiple devices are found, it asks the user to select the device. If one device is found, it returns the address of the device.

Returns:

Device address

Return type:

str

async stream_impedance(mains_freq_60hz=False, handler=None)

Stream impedance data from the Guardian Earbuds. Runs indefinitely until cancelled.

Parameters:

  • mains_freq_60hz (bool, optional) – Set to True if the mains frequency is 60Hz. Defaults to False.

  • handler (callable | None) – The callback function to handle the impedance data. If None is given, the default handler will be used. which simply logs the impedance value to the console.

class idun_guardian_sdk.FileTypes(value)

An enumeration.

EEG = 1
IMPEDANCE = 3
IMU = 2
class idun_guardian_sdk.APIRequestError

Raised for errors during API requests.