feat: add card.power API for Mojo power monitoring

notecard/card.py

@@ -9,7 +9,6 @@
 # This module contains helper methods for calling card.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
@@ -106,7 +105,8 @@ def version(card):
 
 
 @validate_card_object
-def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
+def voltage(card, hours=None, offset=None, vmax=None, vmin=None,
+            usb=None, alert=None):
     """Retrieve current and historical voltage info from the Notecard.
 
     Args:
@@ -115,9 +115,17 @@ def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
         offset (int): Number of hours to offset.
         vmax (decimal): max voltage level to report.
         vmin (decimal): min voltage level to report.
+        usb (bool): Enable USB power state monitoring.
+        alert (bool): Enable alerts for USB power state changes. Only works
+            when usb=True.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing voltage and power
+        state information.
+
+    Note:
+        For Mojo-based power consumption monitoring with temperature and
+        milliamp-hour tracking, see card.power().
     """
     req = {"req": "card.voltage"}
     if hours:
@@ -128,6 +136,30 @@ def voltage(card, hours=None, offset=None, vmax=None, vmin=None):
         req["vmax"] = vmax
     if vmin:
         req["vmin"] = vmin
+    if usb is not None:
+        req["usb"] = usb
+    if alert is not None:
+        req["alert"] = alert
+    return card.Transaction(req)
+
+
+@validate_card_object
+def power(card, minutes=None, reset=None):
+    """Configure and query the Mojo-based power consumption monitoring.
+
+    Args:
+        card (Notecard): The current Notecard object.
+        minutes (int, optional): How often to log power consumption.
+        reset (bool, optional): Reset consumption counters if True.
+
+    Returns:
+        dict: Contains temperature, voltage, and milliamp_hours readings.
+    """
+    req = {"req": "card.power"}
+    if minutes is not None:
+        req["minutes"] = minutes
+    if reset:
+        req["reset"] = True
     return card.Transaction(req)
 
 

test/fluent_api/conftest.py

@@ -9,6 +9,14 @@
 import notecard  # noqa: E402
 
 
+@pytest.fixture
+def card():
+    """Create a mock Notecard instance for testing."""
+    card = notecard.Notecard()
+    card.Transaction = MagicMock()
+    return card
+
+
 @pytest.fixture
 def run_fluent_api_notecard_api_mapping_test():
     def _run_test(fluent_api, notecard_api_name, req_params, rename_map=None):

test/fluent_api/test_card.py

@@ -46,6 +46,28 @@
                 'vmin': 1.2
             }
         ),
+        (
+            card.voltage,
+            'card.voltage',
+            {
+                'usb': True
+            }
+        ),
+        (
+            card.voltage,
+            'card.voltage',
+            {
+                'alert': True
+            }
+        ),
+        (
+            card.voltage,
+            'card.voltage',
+            {
+                'usb': True,
+                'alert': True
+            }
+        ),
         (
             card.wireless,
             'card.wireless',

test/fluent_api/test_card_power.py

@@ -0,0 +1,99 @@
+"""Test power management features in card module."""
+from notecard import card
+
+
+def test_card_power_no_params(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with no parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {}
+    )
+
+
+def test_card_power_minutes(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with minutes parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'minutes': 120}
+    )
+
+
+def test_card_power_reset(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with reset parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'reset': True}
+    )
+
+
+def test_card_power_all_params(run_fluent_api_notecard_api_mapping_test):
+    """Test power() with all parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'minutes': 60, 'reset': True}
+    )
+
+
+def test_card_power_minutes_type(run_fluent_api_notecard_api_mapping_test):
+    """Test that minutes parameter is properly handled as integer."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'minutes': 30}
+    )
+
+
+def test_card_power_reset_type(run_fluent_api_notecard_api_mapping_test):
+    """Test that reset parameter is properly handled as boolean."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.power,
+        'card.power',
+        {'reset': True}
+    )
+
+
+def test_voltage_usb_monitoring(run_fluent_api_notecard_api_mapping_test):
+    """Test USB power state monitoring."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {'usb': True}
+    )
+
+
+def test_voltage_alert_handling(run_fluent_api_notecard_api_mapping_test):
+    """Test alert parameter handling."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {'alert': True}
+    )
+
+
+def test_voltage_usb_with_alert(run_fluent_api_notecard_api_mapping_test):
+    """Test combined USB monitoring and alert functionality."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {'usb': True, 'alert': True}
+    )
+
+
+def test_voltage_with_all_parameters(run_fluent_api_notecard_api_mapping_test):
+    """Test voltage with all available parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        card.voltage,
+        'card.voltage',
+        {
+            'hours': 24,
+            'offset': 1,
+            'vmax': 5.0,
+            'vmin': 3.3,
+            'usb': True,
+            'alert': True
+        }
+    )