microcycler 0.1.0__py3-none-any.whl

microcycler/__init__.py

@@ -0,0 +1,48 @@
+"""
+Microcycler Python SDK
+======================
+
+Python SDK for the Microcycler battery testing platform.
+
+Basic usage::
+
+    import asyncio
+    from microcycler import Cycler
+
+    async def main():
+        async with Cycler("192.168.1.100") as cycler:
+            telemetry = await cycler.get_telemetry()
+            print(f"Voltage: {telemetry.voltage:.3f} V")
+            print(f"Current: {telemetry.current:.3f} A")
+
+    asyncio.run(main())
+
+Recipe usage::
+
+    from microcycler import Cycler
+    from microcycler.recipes import Recipe, CC, CV, Rest, Loop
+
+    recipe = (
+        Recipe()
+        .add(CC(current=1.0, cutoff_voltage=4.2))
+        .add(CV(voltage=4.2, cutoff_current=0.05))
+        .add(Rest(duration=300))
+        .add(Loop(cycles=100))
+    )
+
+    async with Cycler("192.168.1.100") as cycler:
+        await cycler.load_recipe(recipe)
+        await cycler.start()
+"""
+
+from .client import Cycler
+from .types import CyclerTelemetry, CyclerHealth, CyclerLimits, CyclerState
+
+__version__ = "0.1.0"
+__all__ = [
+    "Cycler",
+    "CyclerTelemetry",
+    "CyclerHealth",
+    "CyclerLimits",
+    "CyclerState",
+]

microcycler/client.py

@@ -0,0 +1,187 @@
+"""
+TCP client for communicating with a Microcycler device.
+
+The cycler exposes a SCPI-like command interface over TCP (port 5025) and
+broadcasts UDP telemetry packets for discovery and streaming (port 5026).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from types import TracebackType
+from typing import Optional, Type
+
+from .recipes import Recipe
+from .types import CyclerHealth, CyclerTelemetry
+
+_TCP_PORT = 5025
+_CONNECT_TIMEOUT = 5.0
+_COMMAND_TIMEOUT = 10.0
+
+
+class CyclerError(Exception):
+    """Raised when the cycler returns an error response."""
+
+
+class Cycler:
+    """
+    Async TCP client for a single Microcycler unit.
+
+    Usage as an async context manager is recommended::
+
+        async with Cycler("192.168.1.100") as cycler:
+            telemetry = await cycler.get_telemetry()
+
+    You may also manage the connection manually::
+
+        cycler = Cycler("192.168.1.100")
+        await cycler.connect()
+        try:
+            await cycler.start()
+        finally:
+            await cycler.disconnect()
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int = _TCP_PORT,
+        connect_timeout: float = _CONNECT_TIMEOUT,
+        command_timeout: float = _COMMAND_TIMEOUT,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self._connect_timeout = connect_timeout
+        self._command_timeout = command_timeout
+        self._reader: Optional[asyncio.StreamReader] = None
+        self._writer: Optional[asyncio.StreamWriter] = None
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------
+    # Connection management
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        """Open the TCP connection to the cycler."""
+        self._reader, self._writer = await asyncio.wait_for(
+            asyncio.open_connection(self.host, self.port),
+            timeout=self._connect_timeout,
+        )
+
+    async def disconnect(self) -> None:
+        """Close the TCP connection."""
+        if self._writer is not None:
+            self._writer.close()
+            try:
+                await self._writer.wait_closed()
+            except Exception:
+                pass
+            self._writer = None
+            self._reader = None
+
+    async def __aenter__(self) -> "Cycler":
+        await self.connect()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        await self.disconnect()
+
+    # ------------------------------------------------------------------
+    # Low-level transport
+    # ------------------------------------------------------------------
+
+    async def _send(self, command: str) -> str:
+        """Send a SCPI command and return the response line."""
+        if self._writer is None or self._reader is None:
+            raise CyclerError("Not connected. Call connect() or use as async context manager.")
+
+        async with self._lock:
+            self._writer.write((command.strip() + "\n").encode())
+            await self._writer.drain()
+            response = await asyncio.wait_for(
+                self._reader.readline(),
+                timeout=self._command_timeout,
+            )
+            line = response.decode().strip()
+            if line.startswith("ERR"):
+                raise CyclerError(line)
+            return line
+
+    async def _query_json(self, command: str) -> dict:
+        raw = await self._send(command)
+        return json.loads(raw)
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    async def get_telemetry(self) -> CyclerTelemetry:
+        """Return the current cell telemetry snapshot."""
+        data = await self._query_json("MEAS:TEL?")
+        return CyclerTelemetry.from_dict(data)
+
+    async def get_health(self) -> CyclerHealth:
+        """Return the cycler hardware health snapshot."""
+        data = await self._query_json("MEAS:HEALTH?")
+        return CyclerHealth.from_dict(data)
+
+    async def identify(self) -> str:
+        """Return the cycler identification string (*IDN?)."""
+        return await self._send("*IDN?")
+
+    # ------------------------------------------------------------------
+    # Control
+    # ------------------------------------------------------------------
+
+    async def load_recipe(self, recipe: Recipe) -> None:
+        """Upload a recipe to the cycler's RAM."""
+        payload = json.dumps(recipe.to_dict())
+        await self._send(f"REC:LOAD {payload}")
+
+    async def start(self) -> None:
+        """Start the loaded recipe."""
+        await self._send("REC:START")
+
+    async def pause(self) -> None:
+        """Pause the running recipe."""
+        await self._send("REC:PAUSE")
+
+    async def resume(self) -> None:
+        """Resume a paused recipe."""
+        await self._send("REC:RESUME")
+
+    async def stop(self) -> None:
+        """Abort the running recipe and return to IDLE."""
+        await self._send("REC:STOP")
+
+    async def set_output(self, *, voltage: float, current: float) -> None:
+        """
+        Raw output override (host must remain connected).
+        Intended for direct/manual control outside of a recipe.
+        """
+        await self._send(f"OUT:VOLT {voltage:.4f};OUT:CURR {current:.4f}")
+
+    async def set_limits(
+        self,
+        *,
+        voltage_upper: float,
+        voltage_lower: float,
+        current_upper: float,
+        temperature_upper: float,
+    ) -> None:
+        """Update the safety limits on the cycler."""
+        payload = json.dumps(
+            {
+                "voltage_upper": voltage_upper,
+                "voltage_lower": voltage_lower,
+                "current_upper": current_upper,
+                "temperature_upper": temperature_upper,
+            }
+        )
+        await self._send(f"LIM:SET {payload}")

microcycler/recipes.py

@@ -0,0 +1,130 @@
+"""
+Recipe DSL for building cycler test sequences.
+
+A Recipe is an ordered list of steps. Steps are serialized to JSON and
+uploaded to the cycler via the TCP client (REC:LOAD command).
+
+Example::
+
+    from microcycler.recipes import Recipe, CC, CV, Rest, Loop
+
+    recipe = (
+        Recipe(name="Formation C/10")
+        .add(CC(current=0.1, cutoff_voltage=4.2, cutoff_time=36000))
+        .add(CV(voltage=4.2, cutoff_current=0.02))
+        .add(Rest(duration=1800))
+        .add(CC(current=-0.1, cutoff_voltage=2.8))  # discharge
+        .add(Rest(duration=1800))
+        .add(Loop(cycles=3))
+    )
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, List, Optional
+
+
+# ------------------------------------------------------------------
+# Step base
+# ------------------------------------------------------------------
+
+
+@dataclass
+class _Step:
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["type"] = self.__class__.__name__.upper()
+        return {k: v for k, v in d.items() if v is not None}
+
+
+# ------------------------------------------------------------------
+# Concrete step types
+# ------------------------------------------------------------------
+
+
+@dataclass
+class CC(_Step):
+    """Constant-current step."""
+    current: float
+    cutoff_voltage: Optional[float] = None
+    cutoff_time: Optional[float] = None   # seconds
+    cutoff_capacity: Optional[float] = None  # mAh
+
+
+@dataclass
+class CV(_Step):
+    """Constant-voltage step."""
+    voltage: float
+    cutoff_current: Optional[float] = None
+    cutoff_time: Optional[float] = None
+
+
+@dataclass
+class CP(_Step):
+    """Constant-power step."""
+    power: float                          # watts; positive = charge
+    cutoff_voltage: Optional[float] = None
+    cutoff_time: Optional[float] = None
+
+
+@dataclass
+class CR(_Step):
+    """Constant-resistance step."""
+    resistance: float                     # ohms
+    cutoff_voltage: Optional[float] = None
+    cutoff_time: Optional[float] = None
+
+
+@dataclass
+class Rest(_Step):
+    """Open-circuit rest step."""
+    duration: float                       # seconds
+    cutoff_voltage: Optional[float] = None
+
+
+@dataclass
+class Loop(_Step):
+    """Repeat all preceding steps N times."""
+    cycles: int
+
+
+@dataclass
+class EIS(_Step):
+    """Electrochemical Impedance Spectroscopy sweep."""
+    freq_start: float = 100_000.0         # Hz
+    freq_end: float = 0.01                # Hz
+    amplitude: float = 0.01              # A (perturbation amplitude)
+    points_per_decade: int = 10
+
+
+# ------------------------------------------------------------------
+# Recipe container
+# ------------------------------------------------------------------
+
+
+class Recipe:
+    """
+    An ordered sequence of cycler steps.
+
+    Methods are chainable::
+
+        recipe = Recipe().add(CC(...)).add(CV(...)).add(Rest(...))
+    """
+
+    def __init__(self, name: str = "Untitled Recipe") -> None:
+        self.name = name
+        self._steps: List[_Step] = []
+
+    def add(self, step: _Step) -> "Recipe":
+        self._steps.append(step)
+        return self
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "steps": [s.to_dict() for s in self._steps],
+        }
+
+    def __repr__(self) -> str:
+        return f"Recipe(name={self.name!r}, steps={len(self._steps)})"

microcycler/streaming.py

@@ -0,0 +1,115 @@
+"""
+Async UDP telemetry streaming.
+
+The cycler broadcasts telemetry as UDP JSON packets on port 5026.
+Use CyclerStream to consume these packets as an async iterator, or
+use discover() to find cyclers on the local network.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+from typing import AsyncIterator, List
+
+from .types import CyclerTelemetry
+
+_UDP_PORT = 5026
+_BROADCAST_ADDR = "255.255.255.255"
+_DISCOVERY_TIMEOUT = 3.0
+_MAX_PACKET = 4096
+
+
+class _UDPProtocol(asyncio.DatagramProtocol):
+    def __init__(self, queue: asyncio.Queue) -> None:
+        self._queue = queue
+
+    def datagram_received(self, data: bytes, addr: tuple) -> None:
+        self._queue.put_nowait((data, addr))
+
+    def error_received(self, exc: Exception) -> None:
+        pass
+
+
+class CyclerStream:
+    """
+    Async iterator that yields CyclerTelemetry from UDP broadcast packets.
+
+    Usage::
+
+        async for telemetry in CyclerStream():
+            print(telemetry.voltage, telemetry.current)
+    """
+
+    def __init__(self, host: str = "", port: int = _UDP_PORT) -> None:
+        self._host = host
+        self._port = port
+        self._transport: asyncio.BaseTransport | None = None
+        self._queue: asyncio.Queue = asyncio.Queue()
+
+    async def __aenter__(self) -> "CyclerStream":
+        loop = asyncio.get_running_loop()
+        self._transport, _ = await loop.create_datagram_endpoint(
+            lambda: _UDPProtocol(self._queue),
+            local_addr=(self._host, self._port),
+            allow_broadcast=True,
+        )
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        if self._transport:
+            self._transport.close()
+
+    def __aiter__(self) -> AsyncIterator[CyclerTelemetry]:
+        return self
+
+    async def __anext__(self) -> CyclerTelemetry:
+        data, _ = await self._queue.get()
+        return CyclerTelemetry.from_dict(json.loads(data))
+
+
+async def discover(
+    timeout: float = _DISCOVERY_TIMEOUT,
+    port: int = _UDP_PORT,
+) -> List[str]:
+    """
+    Send a broadcast discovery ping and collect responding cycler IPs.
+
+    Returns a list of IP address strings.
+
+    Usage::
+
+        hosts = await discover()
+        # ['192.168.1.100', '192.168.1.101']
+    """
+    found: dict[str, bool] = {}
+    queue: asyncio.Queue = asyncio.Queue()
+
+    loop = asyncio.get_running_loop()
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    sock.setblocking(False)
+
+    transport, _ = await loop.create_datagram_endpoint(
+        lambda: _UDPProtocol(queue),
+        sock=sock,
+    )
+
+    try:
+        transport.sendto(b"DISC?\n", (_BROADCAST_ADDR, port))
+        deadline = loop.time() + timeout
+        while True:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                break
+            try:
+                _, addr = await asyncio.wait_for(queue.get(), timeout=remaining)
+                found[addr[0]] = True
+            except asyncio.TimeoutError:
+                break
+    finally:
+        transport.close()
+
+    return list(found.keys())

microcycler/types.py

@@ -0,0 +1,66 @@
+"""
+Shared data types mirroring the dashboard's TypeScript definitions in
+dashboard/app/lib/types.ts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Tuple
+
+
+class CyclerState(str, Enum):
+    IDLE = "IDLE"
+    CHARGING = "CHARGING"
+    DISCHARGING = "DISCHARGING"
+    REST = "REST"
+    COMPLETE = "COMPLETE"
+    ERROR = "ERROR"
+
+
+@dataclass
+class CyclerLimits:
+    voltage_upper: float
+    voltage_lower: float
+    current_upper: float
+    temperature_upper: float
+
+
+@dataclass
+class CyclerTelemetry:
+    device_id: str
+    firmware: str
+    hardware: str
+    state: CyclerState
+    voltage: float
+    current: float
+    temperature: float
+    step: int
+    cycle: int
+    elapsed: float
+    capacity_mah: float
+    energy_mwh: float
+    limits: CyclerLimits
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "CyclerTelemetry":
+        limits = CyclerLimits(**data.pop("limits"))
+        return cls(**data, limits=limits)
+
+
+@dataclass
+class CyclerHealth:
+    device_id: str
+    board_temp: float
+    cpu_load_core1: float
+    cpu_load_core2: float
+    heatsink_temps: Tuple[float, float, float, float]
+    main_current_draw: float
+    fan_current_draw: float
+    die_temp: float
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "CyclerHealth":
+        data["heatsink_temps"] = tuple(data["heatsink_temps"])
+        return cls(**data)

microcycler-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: microcycler
+Version: 0.1.0
+Summary: Python SDK for the Microcycler battery testing platform
+Project-URL: Homepage, https://github.com/your-org/microcycler
+Project-URL: Documentation, https://docs.microcycler.io
+Project-URL: Issues, https://github.com/your-org/microcycler/issues
+License: MIT
+Keywords: EIS,battery,cycler,electrochemistry,lab,testing
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: numpy>=1.24; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.24; extra == 'numpy'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# Microcycler Python SDK
+
+Python SDK for the [Microcycler](https://github.com/your-org/microcycler) battery testing platform.
+
+> **Status:** Pre-alpha — API subject to change.
+
+## Installation
+
+```bash
+pip install microcycler
+```
+
+## Quickstart
+
+### Connect and read telemetry
+
+```python
+import asyncio
+from microcycler import Cycler
+
+async def main():
+    async with Cycler("192.168.1.100") as cycler:
+        print(await cycler.identify())
+        t = await cycler.get_telemetry()
+        print(f"State:    {t.state}")
+        print(f"Voltage:  {t.voltage:.3f} V")
+        print(f"Current:  {t.current:.3f} A")
+        print(f"Temp:     {t.temperature:.1f} °C")
+        print(f"Capacity: {t.capacity_mah:.1f} mAh")
+
+asyncio.run(main())
+```
+
+### Discover cyclers on the network
+
+```python
+from microcycler.streaming import discover
+
+hosts = asyncio.run(discover())
+print(hosts)  # ['192.168.1.100', '192.168.1.101']
+```
+
+### Stream live telemetry via UDP
+
+```python
+from microcycler.streaming import CyclerStream
+
+async def monitor():
+    async with CyclerStream() as stream:
+        async for telemetry in stream:
+            print(telemetry.voltage, telemetry.current)
+```
+
+### Build and run a recipe
+
+```python
+from microcycler import Cycler
+from microcycler.recipes import Recipe, CC, CV, Rest, Loop
+
+recipe = (
+    Recipe(name="Standard Formation")
+    .add(CC(current=0.1, cutoff_voltage=4.2))
+    .add(CV(voltage=4.2, cutoff_current=0.02))
+    .add(Rest(duration=1800))
+    .add(CC(current=-0.2, cutoff_voltage=2.8))
+    .add(Rest(duration=1800))
+    .add(Loop(cycles=3))
+)
+
+async def run():
+    async with Cycler("192.168.1.100") as cycler:
+        await cycler.load_recipe(recipe)
+        await cycler.start()
+```
+
+## Recipe steps
+
+| Step | Description |
+|------|-------------|
+| `CC(current, cutoff_voltage, cutoff_time, cutoff_capacity)` | Constant current |
+| `CV(voltage, cutoff_current, cutoff_time)` | Constant voltage |
+| `CP(power, cutoff_voltage, cutoff_time)` | Constant power |
+| `CR(resistance, cutoff_voltage, cutoff_time)` | Constant resistance |
+| `Rest(duration)` | Open-circuit rest |
+| `EIS(freq_start, freq_end, amplitude, points_per_decade)` | Impedance sweep |
+| `Loop(cycles)` | Repeat preceding steps N times |
+
+## License
+
+MIT

microcycler-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+microcycler/__init__.py,sha256=ht91pj4HRWhdDR4ncKtT0noHsnLrza8Nk6V3hCPdxpM,1176
+microcycler/client.py,sha256=oJfSlGHyugcXt8jg79zDRoaEQKRf0Kvq1xa2oHzkzoM,6237
+microcycler/recipes.py,sha256=eqfTxkFNzN_iDIdUbVU3kRA98eXNR8T0pdMgFdCLdCo,3515
+microcycler/streaming.py,sha256=HRhgxV19IgMMmQkrG2fwW2OefuzMWfMFGPsY_hsu5m0,3245
+microcycler/types.py,sha256=QI_US2-M2mMCGErYM_vTqNO8uJYHoW6xC6yZcbtuVK8,1488
+microcycler-0.1.0.dist-info/METADATA,sha256=BkBojCheVRg7zfNRJozDRyMNeBm2dJqyeWCEvUYOtNc,3638
+microcycler-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+microcycler-0.1.0.dist-info/RECORD,,

microcycler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any