{
  "node": {
    "id": "block:balancing-interface",
    "type": "Block",
    "label": "Multi-cell balancing interface",
    "properties": {
      "id": "balancing-interface",
      "name": "Multi-cell balancing interface",
      "kind": "studio",
      "summary": "One to eight independently commanded current-sink circuits with per-cell voltage, current and power; no hardware I/O.",
      "behavior": "One to eight independently commanded current-sink circuits with per-cell voltage, current and power; no hardware I/O. The terminal current participates directly in Kirchhoff current balance and changes the connected battery state. Measurements are solved with the physical network.",
      "ports": [
        {
          "name": "p1",
          "direction": "terminal",
          "unit": "V / A",
          "description": "Electrical conserving connection. Across variables are shared at a node; through flows balance. A pN/nN pair is created for each configured circuit, up to eight."
        },
        {
          "name": "n1",
          "direction": "terminal",
          "unit": "V / A",
          "description": "Electrical conserving connection. Across variables are shared at a node; through flows balance."
        },
        {
          "name": "current1",
          "direction": "input",
          "unit": "A",
          "description": "Optional typed command; otherwise the configured default is used. For balancing, currentN addresses the corresponding circuit."
        },
        {
          "name": "voltage1",
          "direction": "output",
          "unit": "V",
          "description": "Observed voltage1. Each configured circuit has corresponding numbered measurements."
        },
        {
          "name": "current1",
          "direction": "output",
          "unit": "A",
          "description": "Observed current1. Each configured circuit has corresponding numbered measurements."
        },
        {
          "name": "power1",
          "direction": "output",
          "unit": "W",
          "description": "Observed power1. Each configured circuit has corresponding numbered measurements."
        }
      ],
      "parameters": [
        {
          "key": "circuits",
          "label": "Number of balancing circuits",
          "unit": "circuits",
          "default": 1,
          "min": 1,
          "max": 8,
          "description": "Number of balancing circuits. Numerical bounds are model-validation limits, not physical operating ratings."
        },
        {
          "key": "defaultCurrentA",
          "label": "Default current per balancing circuit",
          "unit": "A",
          "default": 0,
          "min": 0,
          "max": 1000000,
          "description": "Default current per balancing circuit. Numerical bounds are model-validation limits, not physical operating ratings."
        }
      ],
      "equations": [
        "I[j] = max(0, commanded current[j])",
        "P[j] = V[j]*I[j]"
      ],
      "example": {
        "title": "Multi-cell balancing interface worked example",
        "text": "The bundled two-cell model commands 0.1 A from circuit 1 and zero from circuit 2. The first cell has 4 V OCV and 0.1 Ω resistance, giving 3.99 V under bleed. The second 3.7 V cell remains unloaded.",
        "url": "https://design.lemonergy.com/cosim.html?example=physical-balancing-interface",
        "label": "Open Studio example",
        "checks": [
          {
            "port": "current1",
            "label": "First bleed current",
            "atS": 1,
            "value": 0.1,
            "unit": "A",
            "tolerance": 1e-06
          },
          {
            "port": "voltage1",
            "label": "First cell voltage",
            "atS": 1,
            "value": 3.99,
            "unit": "V",
            "tolerance": 1e-06
          }
        ],
        "inputs": [
          {
            "port": "current1",
            "label": "Circuit 1 command",
            "value": 0.1,
            "unit": "A"
          }
        ]
      },
      "limits": [
        "This is a simulated electrical interface without a target-hardware driver. SOC and temperature pass-throughs, diagnostic mode flags and hardware-specific communication are outside this interface.",
        "One to eight independently commanded circuits per instance. The default contract shows one circuit; the worked example configures two."
      ],
      "availability": {
        "status": "released",
        "label": "Available in Lemonergy Studio",
        "detail": "The bundled example is available in the production release verified on 28 October 2026. The parameters and examples here are synthetic teaching fixtures, not a characterized cell or a validated operating limit."
      },
      "references": [
        "ti-bms"
      ],
      "evidence": [
        "docs/glossary/native-block-verification.json"
      ],
      "sourceRepository": "Lemonergy Studio public contract",
      "sourceRevision": "verification-2026-10-27",
      "caseIds": [
        "native-balancing-interface"
      ],
      "type": "balancing-interface",
      "implementationId": "balancing-interface",
      "url": "https://lemonergy.com/learn/glossary/blocks/balancing-interface/",
      "documentationUrl": "https://lemonergy.com/learn/glossary/blocks/balancing-interface/",
      "sourceFile": "block-library.json",
      "reviewed": "2026-10-27",
      "releaseEvidence": {
        "environment": "production",
        "status": "verified",
        "revision": "e76cadfc203e15eb41f3478d8b1044a5b851953d",
        "verifiedOn": "2026-10-28",
        "exampleUrls": [
          "https://design.lemonergy.com/cosim.html?example=physical-balancing-interface"
        ]
      }
    }
  },
  "incoming": [
    {
      "id": "edge:usesBlock/native-balancing-interface/0",
      "type": "usesBlock",
      "source": "workflow:native-balancing-interface",
      "target": "block:balancing-interface",
      "properties": {
        "sourceFile": "wiki-blocks.json",
        "position": 0,
        "name": "Multi-cell balancing interface",
        "type": "balancing-interface",
        "role": "One to eight independently commanded current-sink circuits with per-cell voltage, current and power; no hardware I/O. The terminal current participates directly in Kirchhoff current balance and changes the connected battery state. Measurements are solved with the physical network.",
        "settings": [
          "Use the parameter values in the block reference.",
          "Bundled example verified on the production release of 28 October 2026."
        ]
      }
    }
  ],
  "outgoing": [
    {
      "id": "edge:cites/block:balancing-interface/reference:ti-bms",
      "type": "cites",
      "source": "block:balancing-interface",
      "target": "reference:ti-bms",
      "properties": {
        "sourceFile": "block-library.json",
        "scope": "Scientific or mathematical background; implementation scope is stated by the block contract"
      }
    }
  ],
  "neighbors": [
    {
      "id": "workflow:native-balancing-interface",
      "type": "Workflow",
      "label": "Multi-cell balancing interface worked example",
      "properties": {
        "id": "native-balancing-interface",
        "title": "Multi-cell balancing interface worked example",
        "kind": "studio",
        "summary": "One to eight independently commanded current-sink circuits with per-cell voltage, current and power; no hardware I/O.",
        "steps": [
          "Review the block inputs, units and model limits.",
          "Open the Studio example and run its bundled model.",
          "Compare the output channels with the numerical checks; change one input and run again."
        ],
        "example": "The bundled two-cell model commands 0.1 A from circuit 1 and zero from circuit 2. The first cell has 4 V OCV and 0.1 Ω resistance, giving 3.99 V under bleed. The second 3.7 V cell remains unloaded.",
        "observe": "Inspect the outputs and numerical checks on the block reference page.",
        "limits": "This is a simulated electrical interface without a target-hardware driver. SOC and temperature pass-throughs, diagnostic mode flags and hardware-specific communication are outside this interface. One to eight independently commanded circuits per instance. The default contract shows one circuit; the worked example configures two.",
        "url": "https://design.lemonergy.com/cosim.html?example=physical-balancing-interface",
        "label": "Open Studio example",
        "evidence": [
          "docs/glossary/native-block-verification.json"
        ]
      }
    },
    {
      "id": "reference:ti-bms",
      "type": "Reference",
      "label": "Getting Started with the BQ76925",
      "properties": {
        "title": "Getting Started with the BQ76925",
        "publisher": "Texas Instruments",
        "url": "https://www.ti.com/lit/an/slua619b/slua619b.pdf",
        "type": "Application report",
        "scope": "A concrete BMS analog front-end example: cell voltage, current, temperature measurement and MCU integration.",
        "year": 2019,
        "accessed": "2026-10-27"
      }
    }
  ]
}