Utilities

This section shows general objects and helper functions that are used with this package.

General Utilities

class balderhub.ant.lib.utils.PageMessageCollection(initial_messages: list[BaseReceivedAntplusPageTypeT] = None)

Bases: object

Page Message Collection object to manage multiple page messages of the same or different type

append(message: BaseReceivedAntplusPageTypeT) → None

Adds a message to the collection. It will be automatically inserted in the correct order according to its timestamp.

Parameters:: message – the message that should be added to the collection

filter_by_type(page_type: type[BaseReceivedAntplusPageTypeT]) → PageMessageCollection[BaseReceivedAntplusPageTypeT]

Returns a new collection that holds all messages from the given type

Parameters:: page_type – the page type to filter this message collection
Returns:: a new collection that holds all messages from the given type

filter_for_timestamp(start: datetime = None, end: datetime = None) → PageMessageCollection[BaseReceivedAntplusPageTypeT]: This method returns all messages which timestamp is between the given start and/or end date :param start: start (exclusive) timestamp, the messages can have to be returned :param end: end (exclusive) timestamp, the messages can have to be returned :return: a new collection that matches the given filter criteria

get_first_message(of_page_type: type[BaseReceivedAntplusPageTypeT] | None) → BaseReceivedAntplusPageTypeT | None

This method returns the first occurrence of the given page-type within this collection.

Parameters:: of_page_type – the page type to look for
Returns:: the first page-message of the requested type that is within this collection or None if no message of this type was found

get_last_message(of_page_type: type[BaseReceivedAntplusPageTypeT] | None) → BaseReceivedAntplusPageTypeT | None

This method returns the last occurrence of the given page-type within this collection.

Parameters:: of_page_type – the page type to look for
Returns:: the last page-message of the requested type that is within this collection or None if no message of this type was found

get_message_types() → set[type[BaseReceivedAntplusPageTypeT]]

Returns:: returns a set object of all page-message types that exist within this collection

get_unique_value_for_field(field_name: str) → Any | None: This method returns the unique value for one field. It throws an error if the method finds more than one values or if the field does not exist within one or more messages. :param field_name: :return:

get_unique_values_for_field(field_name: str, ignore_non_existing=False) → set[Any]

This method returns a set of values the messages within this collection has. If ignore_non_existing is False the method will raise an exception if there is a message type that does not provide the field_name as property.

Parameters:

field_name – the field name the unique value set should be returned for
ignore_non_existing – True if all messages that does not have this field are ignored, False otherwise (raises an error)

Returns:

the unique set of values that exist within this collection

index(value: BaseReceivedAntplusPageTypeT, start: SupportsIndex = 0, stop: SupportsIndex = 9223372036854775807) → int

Returns the index of the next (similar to list.index)

Parameters:

value – the value to look for
start – first index to look at
stop – last index to look at

Returns:

the index within the internal messsage list

property messages: list[BaseReceivedAntplusPageTypeT]

Returns:: returns a copy of all internal messages

balderhub.ant.lib.utils.filter_hrm_messages_by_toggle_bit_change(messages: PageMessageCollection) → PageMessageCollection

Helper function to filter all messages from a given page-message collection to only return the according to the spec relevant messages, because the toggle bit has changed.

Parameters:: messages – the message collection that should be filtered
Returns:: a new message collection that only holds the first messages after every toggle bit change

Pages

class balderhub.ant.lib.utils.pages.BaseAntplusPage(raw_data: bytes)

Bases: ABC

Base Abstract class describing an ANT+ page

property raw_data: bytes

Returns:: the raw data of this page

class balderhub.ant.lib.utils.pages.BaseReceivedAntplusPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseAntplusPage, ABC

Base ANT+ Page that is intended to be received from a remote ANT+ device (holds a valid timestamp and metadata)

property timestamp: datetime

Note

This is not ment to be a timestamp determined by the ANT host directly. This timestamp is created as soon as the message receives the balderhub python implementation.

Returns:: returns the timestamp the message was received by the feature

Common

class balderhub.ant.lib.utils.pages.common.Common70RequestDataPage(raw_data: bytes)

Bases: BaseAntplusPage

Common data page 70 to request a specific data page from the other device

property command_type: int

Returns:: returns the requested command type

classmethod create(requested_transmission_response: int, requested_page_no: int, command_type: int) → Common70RequestDataPage

Creates a new message type with the provided field values.

Parameters:

requested_transmission_response – the requested transmission response byte
requested_page_no – the page number to request
command_type – the command type to send

Returns:

the ready to send message

property descriptor_byte1

Returns:: returns the descriptor byte 1

property descriptor_byte2

Returns:: returns the descriptor byte 2

property requested_ack_response: bool

Returns:: returns True if the page object asks for a response as ACK message instead of BROADCAST message

property requested_no_of_times: int

Returns:: returns the number of times, the device should respond with the requested page

property requested_page_no: int

Returns:: returns the requested page number

property requested_transmission_response: int

Returns:: returns the requested transmission response

class balderhub.ant.lib.utils.pages.common.Common76ModeSettingsPage(raw_data: bytes)

Bases: BaseAntplusPage

This page allows to change the mode settings of the device.

classmethod create(sport_node: int, sub_sport_mode: int) → Common76ModeSettingsPage

Creates a new message type with the provided field values.

Parameters:

sport_node – the sports mode to set
sub_sport_mode – the sub-sport mode to set

Returns:

the ready to send message

Heart-Rate-Monitor Profile Pages

class balderhub.ant.lib.utils.pages.hrm.BaseHrmPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseReceivedAntplusPage, ABC

Base Heart-Rate-Monitor Page

property computed_heart_rate: int

Returns:: the computed-heart-rate of the current page message

property heart_beat_count: int

Returns:: the raw heart-beat-count of the current page message

property heart_beat_event_time: int

Returns:: the raw heart-beat-event-time of the current page message

property toggle_bit: bool

Returns:: the current state of the toggle bit of the current page message

class balderhub.ant.lib.utils.pages.hrm.Hrm0DefaultDataPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the default data page without any specific information in the page specific bytes.

class balderhub.ant.lib.utils.pages.hrm.Hrm1CumulativeOperationTimePage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the first data page in the HRM profile that holds the cumulative operation time within the page-specific bytes.

property cumulative_operating_time_raw: int

Returns:: returns the raw cumulative operation time (increments every two seconds)

property cumulative_operating_time_sec: int

Returns:: returns the cumulative operation time in seconds

classmethod validate_messages(of_msg_collection: PageMessageCollection) → None

Method to validate the correctness of messages from this type

Parameters:: of_msg_collection – the message collection that should be validated (will automatically be filtered for messages from Hrm1CumulativeOperationTimePage)

class balderhub.ant.lib.utils.pages.hrm.Hrm2ManufacturerInformationPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the second data page in the HRM profile that holds some manufacturer information within the page-specific bytes.

property manufacturer_id: int

Returns:: returns the manufacturer id of the device

property serial_number: int

Returns:: holds the upper 16 bits of the serial number of the device

classmethod validate_messages(of_msg_collection: PageMessageCollection, expected_manufacturer_id: int, expected_serial_number: int) → None

Method to validate the correctness of messages from this type

Parameters:

of_msg_collection – the message collection that should be validated (will automatically be filtered for messages from Hrm2ManufacturerInformationPage)
expected_manufacturer_id – the expected manufacturer id that should be in all messages of this type
expected_serial_number – the expected serial number that should be in all messages of this type

class balderhub.ant.lib.utils.pages.hrm.Hrm3ProductInformationPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the second data page in the HRM profile that holds some product information within the page-specific bytes.

property hardware_version: int

Returns:: returns the hardware version of the device

property model_number: int

Returns:: returns the model number of the device

property software_version: int

Returns:: returns the software version of the device

classmethod validate_messages(of_msg_collection: PageMessageCollection, expected_hardware_version: int, expected_software_version: int, expected_model_number: int) → None

Method to validate the correctness of messages from this type

Parameters:

of_msg_collection – the message collection that should be validated (will automatically be filtered for messages from Hrm3ProductInformationPage)
expected_hardware_version – the expected hardware version that should be in all messages of this type
expected_software_version – the expected software version that should be in all messages of this type
expected_model_number – the expected model number that should be in all messages of this type

Returns:

class balderhub.ant.lib.utils.pages.hrm.Hrm4PreviousHeartBeatEventTimePage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the fourth data page in the HRM profile that can also be used as a main page. It hold some manufacturer specific data and the previous heart beat event time within the page-specific bytes.

property manufacturer_specific_byte: int

Returns:: returns some manufacturer specific information

property previous_heart_beat_event_time_raw: int

Returns:: returns the previous heart beat event time

class balderhub.ant.lib.utils.pages.hrm.Hrm5SwimIntervalSummaryPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the fifth data page in the HRM profile that holds information about swiming intervals within the page-specific bytes.

property interval_average_heart_rate

Returns:: returns the average heart rate within the interval

property interval_maximum_heart_rate

Returns:: returns the maximum heart rate within the interval

property session_average_heart_rate

Returns:: returns the average heart rate within the session

class balderhub.ant.lib.utils.pages.hrm.Hrm6CapabilitiesPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the sixth data page in the HRM profile that holds information about the capabilities within the page-specific bytes.

property extended_cycling_feature_enabled: bool | None

Returns:: returns True if the extended-cycling-feature is enabled, False if it is disabled and None if it is not supported

property extended_running_feature_enabled: bool | None

Returns:: returns True if the extended-running-feature is enabled, False if it is disabled and None if it is not supported

property extended_swimming_feature_enabled: bool | None

Returns:: returns True if the extended-swimming-feature is enabled, False if it is disabled and None if it is not supported

property feature_enabled_byte: int

Returns:: returns the full byte with the information about which features are enabled

property feature_supported_byte: int

Returns:: returns the full byte with the information about which features are supported

property manufacturer_specific_feature_bit6_enabled: bool | None

Returns:: returns True if the manufacturer-specific-bit6 is enabled, False if it is disabled and None if it is not supported

property manufacturer_specific_feature_bit7_enabled: bool | None

Returns:: returns True if the manufacturer-specific-bit7 is enabled, False if it is disabled and None if it is not supported

class balderhub.ant.lib.utils.pages.hrm.Hrm7BatteryStatusPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the seventh data page in the HRM profile that holds information about the battery within the page-specific bytes.

property battery_level: int

Returns:: returns the battery level

property battery_status: int

Returns:: returns the battery status value

property coarse_battery_voltage: int

Returns:: returns the coarse battery voltage value

property descriptive_bit_field: int

Returns:: returns the full raw descriptive bit field

property fractional_battery_voltage: int

Returns:: returns the raw fractional battery voltage if given (use Hrm7BatteryStatusPage.total_battery_voltage() for the full voltage information)

property total_battery_voltage: float | None

Returns:: returns the full battery voltage value or None if it is marked as invalid

classmethod validate_messages(of_msg_collection: PageMessageCollection, expected_battery_level: int, expected_battery_status: int | None, expected_battery_voltage: float | None, allowed_deviation_for_battery_voltage_percent: float = 0.0) → None

Method to validate the correctness of messages from this type

Note that with this check all Battery messages within the provided collection need to have the same value. Split it by yourself in case you need to validate different values.

Parameters:

of_msg_collection – the message collection that should be validated (will automatically be filtered for messages from Hrm7BatteryStatusPage)
expected_battery_level – the expected battery level that should be in all messages of this type
expected_battery_status – the expected battery status that should be in all messages of this type or None, if it is expected that the device sends INVALID (0xF) here
expected_battery_voltage – the expected battery voltage that should be in all messages of this type or None, if it is expected that the device sends INVALID (0xF in coarse voltage) here

class balderhub.ant.lib.utils.pages.hrm.Hrm9DeviceInformationPage(raw_data: bytes, timestamp: float, extended_metas: list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_legacy.BaseExtendedMetaLegacy] | list[balderhub.ant.lib.utils.extended_meta.base_extended_meta_flagged.BaseExtendedMetaFlagged] | None = None)

Bases: BaseHrmPage

This is the ninth data page in the HRM profile that holds some device information within the page-specific bytes.

property heart_beat_event_type: int

Returns:: returns the heart beat event type (0: measured; 1: computed)

classmethod validate_messages(of_msg_collection: PageMessageCollection) → None

Method to validate the correctness of messages from this type

Parameters:: of_msg_collection – the message collection that should be validated (will automatically be filtered for messages from Hrm9DeviceInformationPage)

class balderhub.ant.lib.utils.pages.hrm.Hrm32HrFeaturePage(raw_data: bytes)

Bases: BaseAntplusPage

page for controlling HR features

Extended Metadata

class balderhub.ant.lib.utils.extended_meta.BaseExtendedMetaFlagged(raw_data: bytes)

Bases: object

Base class for Meta data describing data given by the ANT interface in FLAGGED-EXTENDED-DATA message format

property raw_data: bytes

Returns:: returns the raw bytes that describing the information within this metadata object

class balderhub.ant.lib.utils.extended_meta.BaseExtendedMetaLegacy(raw_data: bytes)

Bases: object

Base class for metadata describing data given by the ANT interface in LEGACY-EXTENDED-DATA message format

property raw_data: bytes

Returns:: returns the raw bytes that describing the information within this metadata object

class balderhub.ant.lib.utils.extended_meta.ExtendedMetaFlaggedChannelId(raw_data: bytes)

Bases: BaseExtendedMetaFlagged

Metadata describing data given by the ANT interface in FLAGGED-EXTENDED-DATA message format that describes additional Channel ID information

property device_no: int

Returns:: returns the device number

property device_type: int

Returns:: returns the device type

property transport_type: int

Returns:: returns the transport type

class balderhub.ant.lib.utils.extended_meta.ExtendedMetaFlaggedRssi(raw_data: bytes)

Bases: BaseExtendedMetaFlagged

Metadata describing data given by the ANT interface in FLAGGED-EXTENDED-DATA message format that describes additional RSSI information

property measurement_type: int

Returns:: returns the measurement type

property rssi: int

Returns:: returns the current RSSI value

property threshold_config_value: int

Returns:: returns the threshold config value

class balderhub.ant.lib.utils.extended_meta.ExtendedMetaFlaggedTimestamp(raw_data: bytes)

Bases: BaseExtendedMetaFlagged

Metadata describing data given by the ANT interface in FLAGGED-EXTENDED-DATA message format that describes additional TIMESTAMP information

property timestamp_raw: int

Returns:: returns the raw timestamp value of the message

property timestamp_sec: float

Returns:: returns the timestamp in seconds (rolls over every two second)

class balderhub.ant.lib.utils.extended_meta.ExtendedMetaLegacyChannelId(raw_data: bytes)

Bases: BaseExtendedMetaFlagged

Metadata describing data given by the ANT interface in LEGACY-EXTENDED-DATA message format that describes additional Channel ID information

property device_number: int

Returns:: returns the device number

property device_type: int

Returns:: returns the device type

property trans_type: int

Returns:: returns the transport type