ruuvitag-sensor 2.3.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

ruuvitag_sensor/__init__.py

@@ -1,8 +1,3 @@
-try:
-    import importlib.metadata  # >=3.8
+import importlib.metadata
 
-    __version__ = importlib.metadata.version(__package__ or __name__)  # pylint: disable=no-member
-except ImportError:
-    import importlib_metadata  # <=3.7
-
-    __version__ = importlib_metadata.version(__package__ or __name__)
+__version__ = importlib.metadata.version(__package__ or __name__)

ruuvitag_sensor/__main__.py

@@ -75,6 +75,6 @@ if __name__ == "__main__":
         sys.exit(0)
 
     if is_async_adapter(ruuvitag_sensor.ruuvi.ble):
-        asyncio.get_event_loop().run_until_complete(_async_main_handle(args))
+        asyncio.run(_async_main_handle(args))
     else:
         _sync_main_handle(args)

ruuvitag_sensor/adapters/__init__.py

@@ -1,41 +1,47 @@
 import abc
 import os
-import sys
 from typing import AsyncGenerator, Generator, List
 
 from ruuvitag_sensor.ruuvi_types import MacAndRawData, RawData
 
-# pylint: disable=import-outside-toplevel, cyclic-import
-
 
 def get_ble_adapter():
-    if "bleak" in os.environ.get("RUUVI_BLE_ADAPTER", "").lower():
-        from ruuvitag_sensor.adapters.bleak_ble import BleCommunicationBleak
+    forced_ble_adapter = os.environ.get("RUUVI_BLE_ADAPTER", "").lower()
+    use_ruuvi_nix_from_file = "RUUVI_NIX_FROMFILE" in os.environ
+    is_ci_env = "CI" in os.environ
+
+    if forced_ble_adapter:
+        if "bleak" in forced_ble_adapter:
+            from ruuvitag_sensor.adapters.bleak_ble import BleCommunicationBleak
+
+            return BleCommunicationBleak()
+        if "bleson" in forced_ble_adapter:
+            from ruuvitag_sensor.adapters.bleson import BleCommunicationBleson
+
+            return BleCommunicationBleson()
+        if "bluez" in forced_ble_adapter:
+            from ruuvitag_sensor.adapters.nix_hci import BleCommunicationNix
 
-        return BleCommunicationBleak()
-    if "bleson" in os.environ.get("RUUVI_BLE_ADAPTER", "").lower():
-        from ruuvitag_sensor.adapters.bleson import BleCommunicationBleson
+            return BleCommunicationNix()
 
-        return BleCommunicationBleson()
-    if "RUUVI_NIX_FROMFILE" in os.environ:
+        raise RuntimeError(f"Unknown BLE adapter: {forced_ble_adapter}")
+
+    if use_ruuvi_nix_from_file:
         # Emulate BleCommunicationNix by reading hcidump data from a file
         from ruuvitag_sensor.adapters.nix_hci_file import BleCommunicationNixFile
 
         return BleCommunicationNixFile()
-    if "CI" in os.environ:
-        # Use BleCommunicationDummy for CI as it can't use bluez
+
+    if is_ci_env:
+        # Use BleCommunicationDummy for CI as it can't use Bleak/BlueZ
         from ruuvitag_sensor.adapters.dummy import BleCommunicationDummy
 
         return BleCommunicationDummy()
-    if sys.platform.startswith("win") or sys.platform.startswith("darwin"):
-        from ruuvitag_sensor.adapters.bleak_ble import BleCommunicationBleak
-
-        return BleCommunicationBleak()
 
-    # BlueZ is default for Linux
-    from ruuvitag_sensor.adapters.nix_hci import BleCommunicationNix
+    # Bleak is default adapter for all platforms
+    from ruuvitag_sensor.adapters.bleak_ble import BleCommunicationBleak
 
-    return BleCommunicationNix()
+    return BleCommunicationBleak()
 
 
 def is_async_adapter(ble: object):
@@ -90,5 +96,5 @@ class BleCommunicationAsync:
         # if False: yield is a mypy fix for
         # error: Return type "AsyncGenerator[Tuple[str, str], None]" of "get_data" incompatible with return type
         # "Coroutine[Any, Any, AsyncGenerator[Tuple[str, str], None]]" in supertype "BleCommunicationAsync"
-        if False:  # pylint: disable=unreachable,using-constant-test
+        if False:
             yield 0

ruuvitag_sensor/adapters/bleak_ble.py

@@ -3,34 +3,43 @@ import logging
 import os
 import re
 import sys
-from typing import AsyncGenerator, List, Tuple
+from datetime import datetime
+from typing import AsyncGenerator, List, Optional, Tuple
 
-from bleak import BleakScanner
-from bleak.backends.scanner import AdvertisementData, BLEDevice
+from bleak import BleakClient, BleakGATTCharacteristic, BleakScanner
+from bleak.backends.scanner import AdvertisementData, AdvertisementDataCallback, BLEDevice
 
 from ruuvitag_sensor.adapters import BleCommunicationAsync
+from ruuvitag_sensor.adapters.utils import rssi_to_hex
 from ruuvitag_sensor.ruuvi_types import MacAndRawData, RawData
 
 MAC_REGEX = "[0-9a-f]{2}([:])[0-9a-f]{2}(\\1[0-9a-f]{2}){4}$"
+RUUVI_HISTORY_SERVICE_UUID = "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"
+RUUVI_HISTORY_RX_CHAR_UUID = "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"  # Write
+RUUVI_HISTORY_TX_CHAR_UUID = "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"  # Read and notify
 
 
-def _get_scanner(detection_callback):
+def _get_scanner(detection_callback: AdvertisementDataCallback, bt_device: str = ""):
     # NOTE: On Linux - bleak.exc.BleakError: passive scanning mode requires bluez or_patterns
     # NOTE: On macOS - bleak.exc.BleakError: macOS does not support passive scanning
     scanning_mode = "passive" if sys.platform.startswith("win") else "active"
 
     if "bleak_dev" in os.environ.get("RUUVI_BLE_ADAPTER", "").lower():
-        # pylint: disable=import-outside-toplevel
         from ruuvitag_sensor.adapters.development.dev_bleak_scanner import DevBleakScanner
 
         return DevBleakScanner(detection_callback, scanning_mode)
 
-    return BleakScanner(detection_callback=detection_callback, scanning_mode=scanning_mode)
+    if bt_device:
+        return BleakScanner(
+            detection_callback=detection_callback,
+            scanning_mode=scanning_mode,  # type: ignore[arg-type]
+            adapter=bt_device,
+        )
 
+    return BleakScanner(detection_callback=detection_callback, scanning_mode=scanning_mode)  # type: ignore[arg-type]
 
-# TODO: Python 3.7 - TypeError: 'type' object is not subscriptable
-# queue = asyncio.Queue[Tuple[str, str]]()
-queue = asyncio.Queue()  # type: ignore
+
+queue = asyncio.Queue[Tuple[str, str]]()
 
 log = logging.getLogger(__name__)
 
@@ -71,15 +80,19 @@ class BleCommunicationBleak(BleCommunicationAsync):
             if 1177 not in advertisement_data.manufacturer_data:
                 return
 
+            log.debug("Received data: %s", advertisement_data)
+
             data = BleCommunicationBleak._parse_data(advertisement_data.manufacturer_data[1177])
 
             # Add RSSI to encoded data as hex. All adapters use a common decoder.
-            data += hex((advertisement_data.rssi + (1 << 8)) % (1 << 8)).replace("0x", "")
+            data += rssi_to_hex(advertisement_data.rssi)
             await queue.put((mac, data))
 
-        scanner = _get_scanner(detection_callback)
+        scanner = _get_scanner(detection_callback, bt_device)
         await scanner.start()
 
+        log.debug("Bleak scanner started")
+
         try:
             while True:
                 next_item: Tuple[str, str] = await queue.get()
@@ -93,6 +106,8 @@ class BleCommunicationBleak(BleCommunicationAsync):
 
         await scanner.stop()
 
+        log.debug("Bleak scanner stopped")
+
     @staticmethod
     async def get_first_data(mac: str, bt_device: str = "") -> RawData:
         """
@@ -109,3 +124,139 @@ class BleCommunicationBleak(BleCommunicationAsync):
                 await data_iter.aclose()
 
         return data or ""
+
+    async def get_history_data(
+        self, mac: str, start_time: Optional[datetime] = None, max_items: Optional[int] = None
+    ) -> AsyncGenerator[bytearray, None]:
+        """
+        Get history data from a RuuviTag using GATT connection.
+
+        Args:
+            mac (str): MAC address of the RuuviTag
+            start_time (datetime, optional): Start time for history data
+            max_items (int, optional): Maximum number of history entries to fetch
+
+        Yields:
+            bytearray: Raw history data entries
+
+        Raises:
+            RuntimeError: If connection fails or required services not found
+        """
+        client = None
+        try:
+            log.debug("Connecting to device %s", mac)
+            client = await self._connect_gatt(mac)
+            log.debug("Connected to device %s", mac)
+
+            tx_char, rx_char = self._get_history_service_characteristics(client)
+
+            data_queue: asyncio.Queue[Optional[bytearray]] = asyncio.Queue()
+
+            def notification_handler(_, data: bytearray):
+                # Ignore heartbeat data that starts with 0x05
+                if data and data[0] == 0x05:
+                    log.debug("Ignoring heartbeat data")
+                    return
+                log.debug("Received data: %s", data)
+                # Check for end-of-logs marker (0x3A 0x3A 0x10 0xFF ...)
+                if len(data) >= 3 and all(b == 0xFF for b in data[3:]):
+                    log.debug("Received end-of-logs marker")
+                    data_queue.put_nowait(data)
+                    data_queue.put_nowait(None)
+                    return
+                # Check for error message. Header is 0xF0 (0x30 30 F0 FF FF FF FF FF FF FF FF)
+                if len(data) >= 11 and data[2] == 0xF0:
+                    log.debug("Device reported error in log reading")
+                    data_queue.put_nowait(data)
+                    data_queue.put_nowait(None)
+                    return
+                data_queue.put_nowait(data)
+
+            await client.start_notify(tx_char, notification_handler)
+
+            command = self._create_send_history_command(start_time)
+
+            log.debug("Sending command: %s", command)
+            await client.write_gatt_char(rx_char, command)
+            log.debug("Sent history command to device")
+
+            items_received = 0
+            while True:
+                try:
+                    data = await asyncio.wait_for(data_queue.get(), timeout=10.0)
+                    if data is None:
+                        break
+                    yield data
+                    items_received += 1
+                    if max_items and items_received >= max_items:
+                        break
+                except asyncio.TimeoutError:
+                    log.error("Timeout waiting for history data")
+                    break
+
+        except Exception as e:
+            log.error("Failed to get history data from device %s: %r", mac, e)
+            raise
+        finally:
+            if client:
+                await client.disconnect()
+                log.debug("Disconnected from device %s", mac)
+
+    async def _connect_gatt(self, mac: str, max_retries: int = 3) -> BleakClient:
+        # Connect to a BLE device using GATT.
+        # NOTE: On macOS, the device address is not a MAC address, but a system specific ID
+        client = BleakClient(mac)
+
+        for attempt in range(max_retries):
+            try:
+                await client.connect()
+                return client
+            except Exception as e:  # noqa: PERF203
+                if attempt == max_retries - 1:
+                    raise
+                log.debug("Connection attempt %s failed: %s - Retrying...", attempt + 1, str(e))
+                await asyncio.sleep(1)
+
+        return client  # Satisfy linter - this line will never be reached
+
+    def _get_history_service_characteristics(
+        self, client: BleakClient
+    ) -> Tuple[BleakGATTCharacteristic, BleakGATTCharacteristic]:
+        # Get the history service
+        # https://docs.ruuvi.com/communication/bluetooth-connection/nordic-uart-service-nus
+        history_service = next(
+            (service for service in client.services if service.uuid.lower() == RUUVI_HISTORY_SERVICE_UUID.lower()),
+            None,
+        )
+        if not history_service:
+            raise RuntimeError("History service not found - device may not support history")
+
+        tx_char = history_service.get_characteristic(RUUVI_HISTORY_TX_CHAR_UUID)
+        rx_char = history_service.get_characteristic(RUUVI_HISTORY_RX_CHAR_UUID)
+
+        if not tx_char or not rx_char:
+            raise RuntimeError("Required characteristics not found")
+
+        return tx_char, rx_char
+
+    def _create_send_history_command(self, start_time):
+        end_time = int(datetime.now().timestamp())
+        start_time_to_use = int(start_time.timestamp()) if start_time else 0
+
+        command = bytearray(
+            [
+                0x3A,
+                0x3A,
+                0x11,  # Header for temperature query
+                (end_time >> 24) & 0xFF,  # End timestamp byte 1 (most significant)
+                (end_time >> 16) & 0xFF,  # End timestamp byte 2
+                (end_time >> 8) & 0xFF,  # End timestamp byte 3
+                end_time & 0xFF,  # End timestamp byte 4
+                (start_time_to_use >> 24) & 0xFF,  # Start timestamp byte 1 (most significant)
+                (start_time_to_use >> 16) & 0xFF,  # Start timestamp byte 2
+                (start_time_to_use >> 8) & 0xFF,  # Start timestamp byte 3
+                start_time_to_use & 0xFF,  # Start timestamp byte 4
+            ]
+        )
+
+        return command

ruuvitag_sensor/adapters/bleson.py

@@ -8,12 +8,11 @@ from typing import Generator, List
 from bleson import Observer, get_provider
 
 from ruuvitag_sensor.adapters import BleCommunication
+from ruuvitag_sensor.adapters.utils import rssi_to_hex
 from ruuvitag_sensor.ruuvi_types import MacAndRawData, RawData
 
 log = logging.getLogger(__name__)
 
-# pylint: disable=duplicate-code
-
 
 class BleCommunicationBleson(BleCommunication):
     """Bluetooth LE communication with Bleson"""
@@ -56,6 +55,9 @@ class BleCommunicationBleson(BleCommunication):
                 data = f"FF{data.hex()}"
                 data = f"{(len(data) >> 1):02x}{data}"
                 data = f"{(len(data) >> 1):02x}{data}"
+
+                # Add RSSI to encoded data as hex. All adapters use a common decoder.
+                data += rssi_to_hex(advertisement.rssi)
                 queue.put((mac, data.upper()))
             except GeneratorExit:
                 break
@@ -72,11 +74,8 @@ class BleCommunicationBleson(BleCommunication):
            device (string): BLE device (default 0)
         """
 
-        if not bt_device:
-            bt_device = 0
-        else:
-            # Old communication used hci0 etc.
-            bt_device = bt_device.replace("hci", "")
+        # Old communication used hci0 etc.
+        bt_device = 0 if not bt_device else bt_device.replace("hci", "")
 
         log.info("Start receiving broadcasts (device %s)", bt_device)
 

ruuvitag_sensor/adapters/development/dev_bleak_scanner.py

@@ -33,11 +33,9 @@ class DevBleakScanner:
     async def start(self):
         self.running = True
         asyncio.create_task(self.run())
-        return None
 
     async def stop(self):
         self.running = False
-        return None
 
     async def run(self):
         while self.running:

ruuvitag_sensor/adapters/nix_hci.py

@@ -10,8 +10,6 @@ from ruuvitag_sensor.ruuvi_types import MacAndRawData, RawData
 
 log = logging.getLogger(__name__)
 
-# pylint: disable=duplicate-code
-
 
 class BleCommunicationNix(BleCommunication):
     """Bluetooth LE communication for Linux"""
@@ -24,12 +22,12 @@ class BleCommunicationNix(BleCommunication):
         """
         # import ptyprocess here so as long as all implementations are in
         # the same file, all will work
-        import ptyprocess  # pylint: disable=import-outside-toplevel
+        import ptyprocess
 
         if not bt_device:
             bt_device = "hci0"
 
-        is_root = os.getuid() == 0  # pylint: disable=no-member
+        is_root = os.getuid() == 0
 
         log.info("Start receiving broadcasts (device %s)", bt_device)
         DEVNULL = subprocess.DEVNULL
@@ -95,9 +93,8 @@ class BleCommunicationNix(BleCommunication):
                     data = line[2:].replace(" ", "")
                 elif line.startswith("< "):
                     data = None
-                else:
-                    if data:
-                        data += line.replace(" ", "")
+                elif data:
+                    data += line.replace(" ", "")
         except KeyboardInterrupt:
             return
         except Exception as ex:
@@ -112,7 +109,7 @@ class BleCommunicationNix(BleCommunication):
             log.debug("Parsing line %s", line)
             try:
                 # Make sure we're in upper case
-                line = line.upper()
+                line = line.upper()  # noqa: PLW2901
                 # We're interested in LE meta events, sent by Ruuvitags.
                 # Those start with "043E", followed by a length byte.
 

ruuvitag_sensor/adapters/nix_hci_file.py

@@ -1,5 +1,7 @@
 import logging
 
+import Path
+
 from ruuvitag_sensor.adapters.nix_hci import BleCommunicationNix
 
 log = logging.getLogger(__name__)
@@ -19,7 +21,7 @@ class BleCommunicationNixFile(BleCommunicationNix):
            This is interpreted as a file to open
         """
         log.info("Start reading from file %s", bt_device)
-        handle = open(bt_device, "rb")  # pylint: disable=consider-using-with
+        handle = Path.open(bt_device, "rb")
 
         return (None, handle)
 

ruuvitag_sensor/adapters/utils.py

@@ -0,0 +1,2 @@
+def rssi_to_hex(rssi: int) -> str:
+    return f"{(rssi + (1 << 8)) % (1 << 8):x}"

ruuvitag_sensor/data_formats.py

@@ -35,9 +35,8 @@ class DataFormats:
     RuuviTag broadcasted raw data handling for each data format
     """
 
-    # pylint: disable=too-many-return-statements
     @staticmethod
-    def convert_data(raw: str) -> DataFormatAndRawSensorData:
+    def convert_data(raw: str) -> DataFormatAndRawSensorData:  # noqa: PLR0911
         """
         Validate that data is from RuuviTag and get correct data part.
 
@@ -78,7 +77,7 @@ class DataFormats:
                     break
         except ShortDataError as ex:
             # Data might be from RuuviTag, but received data was invalid
-            # e.g. it's possile that bluetooth stack received only partial data
+            # e.g. it's possible that Bluetooth stack received only partial data
             # Set the format to None, and data to '', this allows the
             # caller to determine that we did indeed see a Ruuvitag.
             log.debug("Error parsing advertisement data: %s", ex)
@@ -118,7 +117,7 @@ class DataFormats:
         return (None, None)
 
     @staticmethod
-    def _parse_raw(raw: str, data_format: int) -> str:  # pylint: disable=unused-argument
+    def _parse_raw(raw: str, data_format: int) -> str:
         return raw
 
     @staticmethod

ruuvitag_sensor/decoder.py

@@ -4,7 +4,7 @@ import math
 import struct
 from typing import Optional, Tuple, Union
 
-from ruuvitag_sensor.ruuvi_types import ByteData, SensorData3, SensorData5, SensorDataUrl
+from ruuvitag_sensor.ruuvi_types import ByteData, SensorData3, SensorData5, SensorDataUrl, SensorHistoryData
 
 log = logging.getLogger(__name__)
 
@@ -282,3 +282,135 @@ class Df5Decoder:
         except Exception:
             log.exception("Value: %s not valid", data)
             return None
+
+
+class HistoryDecoder:
+    """
+    Decodes history data from RuuviTag
+    Protocol specification:
+    https://github.com/ruuvi/docs/blob/master/communication/bluetooth-connection/nordic-uart-service-nus/log-read.md
+
+    Data format:
+    - First byte: Command byte (0x3A)
+    - Second byte: Packet type (0x30 = temperature, 0x31 = humidity, 0x32 = pressure)
+    - Third byte: Header byte (skipped or error)
+    - Next 4 bytes: Clock time (seconds since unix epoch)
+    - Next 2 bytes: Reserved (always 0x00)
+    - Next 2 bytes: Sensor data (uint16, little-endian)
+        Temperature: 0.01°C units
+        Humidity: 0.01% units
+        Pressure: Raw value in hPa
+
+    Special case:
+    - End marker packet has command byte 0x3A followed by 0x3A
+    """
+
+    def _is_error_packet(self, data: list[str]) -> bool:
+        """Check if this is an error packet"""
+        return data[2] == "F0" and all(b == "ff" for b in data[3:])
+
+    def _is_end_marker(self, data: list[str]) -> bool:
+        """Check if this is an end marker packet"""
+        # Check for command byte 0x3A, type 0x3A, and remaining bytes are 0xFF
+        return data[0] == "3a" and data[1] == "3a" and all(b == "ff" for b in data[3:])
+
+    def _get_timestamp(self, data: list[str]) -> int:
+        """Return timestamp"""
+        # The timestamp is a 4-byte value after the header byte, in seconds since Unix epoch
+        timestamp_bytes = bytes.fromhex("".join(data[3:7]))
+        timestamp = int.from_bytes(timestamp_bytes, "big")
+        return timestamp
+        # return datetime.fromtimestamp(timestamp, tz=timezone.utc)
+
+    def _get_temperature(self, data: list[str]) -> Optional[float]:
+        """Return temperature in celsius"""
+        if data[1] != "30":  # '0' for temperature
+            return None
+        # Temperature is in 0.01°C units, little-endian
+        temp_bytes = bytes.fromhex("".join(data[9:11]))
+        temp_raw = int.from_bytes(temp_bytes, "big")
+        return round(temp_raw * 0.01, 2)
+
+    def _get_humidity(self, data: list[str]) -> Optional[float]:
+        """Return humidity %"""
+        if data[1] != "31":  # '1' for humidity
+            return None
+        # Humidity is in 0.01% units, little-endian
+        humidity_bytes = bytes.fromhex("".join(data[9:11]))
+        humidity_raw = int.from_bytes(humidity_bytes, "big")
+        return round(humidity_raw * 0.01, 2)
+
+    def _get_pressure(self, data: list[str]) -> Optional[float]:
+        """Return air pressure hPa"""
+        if data[1] != "32":  # '2' for pressure
+            return None
+        # Pressure is in hPa units, little-endian
+        pressure_bytes = bytes.fromhex("".join(data[9:11]))
+        pressure_raw = int.from_bytes(pressure_bytes, "big")
+        return float(pressure_raw)
+
+    def decode_data(self, data: bytearray) -> Optional[SensorHistoryData]:  # noqa: PLR0911
+        """
+        Decode history data from RuuviTag.
+
+        The data format follows the NUS log format.
+
+        Args:
+            data: Raw history data bytearray
+
+        Returns:
+            SensorDataHistory: Decoded sensor values with timestamp, or None if decoding fails
+            Returns None for both invalid data and end marker packets
+        """
+        try:
+            hex_values = [format(x, "02x") for x in data]
+
+            if len(hex_values) != 11:
+                log.info("History data too short: %d bytes", len(hex_values))
+                return None
+
+            # Verify this is a history log entry
+            if hex_values[0] != "3a":  # ':'
+                log.info("Invalid command byte: %d", data[0])
+                return None
+
+            # Check for error header
+            if self._is_error_packet(hex_values):
+                log.info("Device reported error in log reading")
+                return None
+
+            # Check for end marker packet
+            if self._is_end_marker(hex_values):
+                log.debug("End marker packet received")
+                return None
+
+            # Each packet type contains one measurement
+            packet_type = hex_values[1]
+            if packet_type == "30":  # '0' temperature
+                return {
+                    "temperature": self._get_temperature(hex_values),
+                    "humidity": None,
+                    "pressure": None,
+                    "timestamp": self._get_timestamp(hex_values),
+                }
+            elif packet_type == "31":  # '1' humidity
+                return {
+                    "temperature": None,
+                    "humidity": self._get_humidity(hex_values),
+                    "pressure": None,
+                    "timestamp": self._get_timestamp(hex_values),
+                }
+            elif packet_type == "32":  # '2' pressure
+                return {
+                    "temperature": None,
+                    "humidity": None,
+                    "pressure": self._get_pressure(hex_values),
+                    "timestamp": self._get_timestamp(hex_values),
+                }
+            else:
+                log.info("Invalid packet type: %d - %s", packet_type, data)
+                return None
+
+        except Exception:
+            log.exception("Value not valid: %s", data)
+            return None

ruuvitag_sensor/log.py

@@ -1,27 +1,44 @@
 """
-ruuvitag_sensor module level logging
+Module level logging configuration for ruuvitag_sensor package.
+
+This module provides:
+1. A root logger for the package with default ERROR level file logging
+2. A function to enable console output, primarily for CLI usage
+
+Note: Applications using this package as a library should configure their own logging
+rather than relying on this module's configuration.
 """
 
 import logging
 
+# Create the package's root logger
 log = logging.getLogger("ruuvitag_sensor")
 log.setLevel(logging.INFO)
 
-# create a file handler
+# Configure file logging for errors
 file_handler = logging.FileHandler("ruuvitag_sensor.log")
 file_handler.setLevel(logging.ERROR)
 
-# create a logging format
+# Set up a standard logging format with timestamp, logger name, level and message
 formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
-
 file_handler.setFormatter(formatter)
-
-# add the handlers to the logger
 log.addHandler(file_handler)
 
 
-def enable_console():
+def enable_console(level: int = logging.INFO) -> None:
+    """Enable console logging for the package.
+
+    This function is primarily intended for command-line usage of the package.
+    If the requested level is DEBUG, it will also set the root logger's level to DEBUG.
+    The function ensures only one console handler is added.
+
+    Args:
+        level: The logging level for console output. Defaults to INFO.
+    """
+    if level < logging.INFO:
+        log.setLevel(level)
+
     if len(log.handlers) != 2:
         console_handler = logging.StreamHandler()
-        console_handler.setLevel(logging.INFO)
+        console_handler.setLevel(level)
         log.addHandler(console_handler)