Add EC memory map abstractions

Author: Steve-Tech

cros_ec_python/__init__.py

@@ -1,3 +1,3 @@
 from .cros_ec import CrOS_EC, DeviceTypes
-from .commands import general, features, pwm, leds, thermal
+from .commands import memmap, general, features, pwm, leds, thermal
 from .exceptions import ECError

cros_ec_python/commands/general.py

@@ -46,20 +46,20 @@ def get_version(ec: CrOS_EC, version: Literal[0, 1] = 0) -> dict[str, str | int]
             resp = ec.command(version, EC_CMD_GET_VERSION, 0, 32 + 32 + 32 + 4)
             unpacked = struct.unpack("<32s32s32sI", resp)
             return {
-                "version_string_ro": unpacked[0].decode("utf-8").strip("\x00"),
-                "version_string_rw": unpacked[1].decode("utf-8").strip("\x00"),
-                "reserved": unpacked[2].decode("utf-8").strip("\x00"),
+                "version_string_ro": unpacked[0].decode("utf-8").rstrip("\x00"),
+                "version_string_rw": unpacked[1].decode("utf-8").rstrip("\x00"),
+                "reserved": unpacked[2].decode("utf-8").rstrip("\x00"),
                 "current_image": unpacked[3]
             }
         case 1:
             resp = ec.command(version, EC_CMD_GET_VERSION, 0, 32 + 32 + 32 + 4 + 32)
             unpacked = struct.unpack("<32s32s32sI32s", resp)
             return {
-                "version_string_ro": unpacked[0].decode("utf-8").strip("\x00"),
-                "version_string_rw": unpacked[1].decode("utf-8").strip("\x00"),
-                "cros_fwid_ro": unpacked[2].decode("utf-8").strip("\x00"),
+                "version_string_ro": unpacked[0].decode("utf-8").rstrip("\x00"),
+                "version_string_rw": unpacked[1].decode("utf-8").rstrip("\x00"),
+                "cros_fwid_ro": unpacked[2].decode("utf-8").rstrip("\x00"),
                 "current_image": unpacked[3],
-                "crod_fwid_rw": unpacked[4].decode("utf-8").strip("\x00")
+                "crod_fwid_rw": unpacked[4].decode("utf-8").rstrip("\x00")
             }
         case _:
             raise NotImplementedError
@@ -78,7 +78,7 @@ def get_build_info(ec: CrOS_EC) -> str:
     @return: The build info as a string.
     """
     resp = ec.command(0, EC_CMD_GET_BUILD_INFO, 0, 0xfc, warn=False)
-    return resp.decode("utf-8").strip("\x00")
+    return resp.decode("utf-8").rstrip("\x00")
 
 
 EC_CMD_GET_CHIP_INFO: Final = 0x0005
@@ -93,9 +93,9 @@ def get_chip_info(ec: CrOS_EC) -> dict[str, str]:
     resp = ec.command(0, EC_CMD_GET_CHIP_INFO, 0, 32 + 32 + 32)
     unpacked = struct.unpack("<32s32s32s", resp)
     return {
-        "vendor": unpacked[0].decode("utf-8").strip("\x00"),
-        "name": unpacked[1].decode("utf-8").strip("\x00"),
-        "revision": unpacked[2].decode("utf-8").strip("\x00")
+        "vendor": unpacked[0].decode("utf-8").rstrip("\x00"),
+        "name": unpacked[1].decode("utf-8").rstrip("\x00"),
+        "revision": unpacked[2].decode("utf-8").rstrip("\x00")
     }
 
 

cros_ec_python/commands/memmap.py

@@ -0,0 +1,125 @@
+import struct
+from ..cros_ec import CrOS_EC
+from ..constants.COMMON import *
+from ..constants.MEMMAP import *
+
+
+def get_temps(ec: CrOS_EC, adjust: int | float = -273) -> list[int | float]:
+    """
+    Get the temperature of all temp sensors.
+    @param ec: The CrOS_EC object.
+    @param adjust: The adjustment to apply to the temperature. Default is -273 to convert from Kelvin to Celsius.
+    @return: A list of temperatures.
+    """
+    version = int(ec.memmap(EC_MEMMAP_THERMAL_VERSION, 1)[0])
+    if not version:
+        # No temp sensors supported
+        return []
+
+    ret = []
+    if version >= 1:
+        resp = ec.memmap(EC_MEMMAP_TEMP_SENSOR, EC_TEMP_SENSOR_ENTRIES)
+        temps = struct.unpack(f"<{EC_TEMP_SENSOR_ENTRIES}B", resp)
+        ret += [temp + EC_TEMP_SENSOR_OFFSET + adjust for temp in temps if temp < 0xFC]
+
+    if version >= 2:
+        resp = ec.memmap(EC_MEMMAP_TEMP_SENSOR_B, EC_TEMP_SENSOR_B_ENTRIES)
+        temps = struct.unpack(f"<{EC_TEMP_SENSOR_B_ENTRIES}B", resp)
+        ret += [temp + EC_TEMP_SENSOR_OFFSET + adjust for temp in temps if temp < 0xFC]
+
+    return ret
+
+
+def get_fans(ec: CrOS_EC) -> list[int | None]:
+    """
+    Get the speed of all fans.
+    @param ec: The CrOS_EC object.
+    @return: A list of fan speeds. None if the fan has stalled.
+    """
+    version = int(ec.memmap(EC_MEMMAP_THERMAL_VERSION, 1)[0])
+    if not version:
+        # No fans supported
+        return []
+
+    resp = ec.memmap(EC_MEMMAP_FAN, EC_FAN_SPEED_ENTRIES * 2)  # 2 bytes per fan
+    fans = struct.unpack(f"<{EC_FAN_SPEED_ENTRIES}H", resp)
+    return [None if fan is EC_FAN_SPEED_STALLED else fan for fan in fans if fan < EC_FAN_SPEED_NOT_PRESENT]
+
+
+def get_switches(ec: CrOS_EC) -> dict[str, bool]:
+    """
+    Get the state of the switches.
+    @param ec: The CrOS_EC object.
+    @return: The state of the switches.
+    """
+    version = int(ec.memmap(EC_MEMMAP_SWITCHES_VERSION, 1)[0])
+    if not version:
+        # No switches supported
+        return {}
+
+    resp = ec.memmap(EC_MEMMAP_SWITCHES, 1)[0]
+    return {
+        "lid_open": bool(resp & EC_SWITCH_LID_OPEN),
+        "power_button_pressed": bool(resp & EC_SWITCH_POWER_BUTTON_PRESSED),
+        "write_protect_disabled": bool(resp & EC_SWITCH_WRITE_PROTECT_DISABLED),
+        "dedicated_recovery": bool(resp & EC_SWITCH_DEDICATED_RECOVERY)
+    }
+
+
+def get_battery_values(ec: CrOS_EC) -> dict[str, int | bool | str]:
+    """
+    Get the values of the battery.
+    @param ec: The CrOS_EC object.
+    @return: The state of the battery.
+    """
+    version = int(ec.memmap(EC_MEMMAP_BATTERY_VERSION, 1)[0])
+    if not version:
+        # No battery supported
+        return {}
+
+    resp = ec.memmap(EC_MEMMAP_BATT_VOLT, EC_MEMMAP_ALS - EC_MEMMAP_BATT_VOLT)
+    data = struct.unpack("<IIIBBBxIIII8s8s8s8s", resp)
+    return {
+        "volt": data[0],
+        "rate": data[1],
+        "capacity": data[2],
+        "ac_present": bool(data[3] & EC_BATT_FLAG_AC_PRESENT),
+        "batt_present": bool(data[3] & EC_BATT_FLAG_BATT_PRESENT),
+        "discharging": bool(data[3] & EC_BATT_FLAG_DISCHARGING),
+        "charging": bool(data[3] & EC_BATT_FLAG_CHARGING),
+        "level_critical": bool(data[3] & EC_BATT_FLAG_LEVEL_CRITICAL),
+        "invalid_data": bool(data[3] & EC_BATT_FLAG_INVALID_DATA),
+        "count": data[4],
+        "index": data[5],
+        "design_capacity": data[6],
+        "design_voltage": data[7],
+        "last_full_charge_capacity": data[8],
+        "cycle_count": data[9],
+        "manufacturer": data[10].decode("utf-8").rstrip("\x00"),
+        "model": data[11].decode("utf-8").rstrip("\x00"),
+        "serial": data[12].decode("utf-8").rstrip("\x00"),
+        "type": data[13].decode("utf-8").rstrip("\x00")
+    }
+
+
+def get_als(ec: CrOS_EC) -> list[int | None]:
+    """
+    Get the current value from all Ambient Light Sensors.
+    @param ec: The CrOS_EC object.
+    @return: A list of ALS values. May be 0 if the sensor is not present.
+    """
+    resp = ec.memmap(EC_MEMMAP_ALS, EC_ALS_ENTRIES * 2)  # 2 bytes per sensor
+    als = struct.unpack(f"<{EC_ALS_ENTRIES}H", resp)
+    return [val for val in als]
+
+
+def get_accel(ec: CrOS_EC) -> list[int | None]:
+    """
+    Get the current value from all accelerometers.
+    @param ec: The CrOS_EC object.
+    @return: A list of accelerometer values. May be 0 if the sensor is not present.
+    """
+    EC_ACC_ENTRIES: Final = 3
+    resp = ec.memmap(EC_MEMMAP_ACC_DATA, EC_ACC_ENTRIES * 2)  # 2 bytes per sensor
+    accel = struct.unpack(f"<{EC_ACC_ENTRIES}H", resp)
+    return [val for val in accel]

cros_ec_python/constants/MEMMAP.py

@@ -8,7 +8,7 @@
 EC_MEMMAP_TEMP_SENSOR      : Final = 0x00 # Temp sensors 0x00 - 0x0f
 EC_MEMMAP_FAN              : Final = 0x10 # Fan speeds 0x10 - 0x17
 EC_MEMMAP_TEMP_SENSOR_B    : Final = 0x18 # More temp sensors 0x18 - 0x1f
-EC_MEMMAP_ID               : Final = 0x20 # 0x20 : Final =: Final = 'E', 0x21 : Final =: Final = 'C'
+EC_MEMMAP_ID               : Final = 0x20 # 0x20 == 'E', 0x21 == 'C'
 EC_MEMMAP_ID_VERSION       : Final = 0x22 # Version of data in 0x20 - 0x2f
 EC_MEMMAP_THERMAL_VERSION  : Final = 0x23 # Version of data in 0x00 - 0x1f
 EC_MEMMAP_BATTERY_VERSION  : Final = 0x24 # Version of data in 0x40 - 0x7f
@@ -64,7 +64,7 @@
 
 # Number of temp sensors at EC_MEMMAP_TEMP_SENSOR_B.
 #
-# Valid only if EC_MEMMAP_THERMAL_VERSION returns >: Final = 2.
+# Valid only if EC_MEMMAP_THERMAL_VERSION returns >= 2.
 
 EC_TEMP_SENSOR_B_ENTRIES      : Final = 8
 
@@ -75,7 +75,7 @@
 EC_TEMP_SENSOR_NOT_CALIBRATED : Final = 0xfc
 
 # The offset of temperature value stored in mapped memory.  This allows
-# reporting a temperature range of 200K to 454K : Final = -73C to 181C.
+# reporting a temperature range of 200K to 454K = -73C to 181C.
 
 EC_TEMP_SENSOR_OFFSET      : Final = 200
 

tests/memmap.py

@@ -0,0 +1,50 @@
+import unittest
+from cros_ec_python import CrOS_EC, memmap as ec_memmap
+
+ec = CrOS_EC()
+
+
+class TestGetTemps(unittest.TestCase):
+    def test(self):
+        resp = ec_memmap.get_temps(ec)
+        print(type(self).__name__, "-", "Resp:", resp)
+        self.assertIsInstance(resp, list)
+
+
+class TestGetFans(unittest.TestCase):
+    def test(self):
+        resp = ec_memmap.get_fans(ec)
+        print(type(self).__name__, "-", "Resp:", resp)
+        self.assertIsInstance(resp, list)
+
+
+class TestGetSwitches(unittest.TestCase):
+    def test(self):
+        resp = ec_memmap.get_switches(ec)
+        print(type(self).__name__, "-", "Resp:", resp)
+        self.assertIsInstance(resp, dict)
+
+
+class TestGetBattery(unittest.TestCase):
+    def test(self):
+        resp = ec_memmap.get_battery_values(ec)
+        print(type(self).__name__, "-", "Resp:", resp)
+        self.assertIsInstance(resp, dict)
+
+
+class TestGetALS(unittest.TestCase):
+    def test(self):
+        resp = ec_memmap.get_als(ec)
+        print(type(self).__name__, "-", "Resp:", resp)
+        self.assertIsInstance(resp, list)
+
+
+class TestGetAccel(unittest.TestCase):
+    def test(self):
+        resp = ec_memmap.get_accel(ec)
+        print(type(self).__name__, "-", "Resp:", resp)
+        self.assertIsInstance(resp, list)
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/tests.py

@@ -1,4 +1,5 @@
 import unittest
+from memmap import *
 from general import *
 from features import *
 # These have some user input, uncomment if you're human.