{
  "node": {
    "id": "block:battery-cccv-controller",
    "type": "Block",
    "label": "CC-CV current controller",
    "properties": {
      "id": "battery-cccv-controller",
      "name": "CC-CV current controller",
      "kind": "studio",
      "summary": "PI voltage regulation with an external current envelope and anti-windup.",
      "behavior": "Uses a PI voltage loop and an external current magnitude envelope to request charge current. Conditional integration limits windup while the request is saturated. Charging is negative in the discharge-positive current convention; disabling resets control memory.",
      "ports": [
        {
          "name": "voltage",
          "direction": "input",
          "unit": "V",
          "description": "Highest cell voltage; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "limit",
          "direction": "input",
          "unit": "A",
          "description": "Charge-current magnitude limit; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "current"
        },
        {
          "name": "enable",
          "direction": "input",
          "unit": "true / false",
          "description": "Enable; scalar.",
          "shape": [],
          "elementType": "bool",
          "quantity": "dimensionless"
        },
        {
          "name": "request",
          "direction": "output",
          "unit": "A",
          "description": "Signed current request (charge negative); scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "current"
        },
        {
          "name": "mode",
          "direction": "output",
          "unit": "1",
          "description": "Mode (0 disabled, 1 CC, 2 CV); scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        }
      ],
      "parameters": [
        {
          "key": "sampleTimeS",
          "label": "Sample interval (s)",
          "unit": "s",
          "default": 0.1,
          "description": "Positive sample interval. Initialization has zero elapsed time; subsequent accepted samples update memory."
        },
        {
          "key": "targetV",
          "label": "Voltage target (V)",
          "unit": "V",
          "default": 4,
          "description": "Voltage target (V). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "kp",
          "label": "Proportional gain (A/V)",
          "unit": "A/V",
          "default": 10,
          "description": "Proportional gain (A/V). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "ki",
          "label": "Integral gain (A/(V·s))",
          "unit": "A/(V·s)",
          "default": 0,
          "description": "Integral gain (A/(V·s)). This is an editable model input; the default belongs to the synthetic worked example."
        }
      ],
      "equations": [
        "error = targetV - highestCellVoltage",
        "request = -clamp(kp * error + integral, 0, currentLimit)"
      ],
      "example": {
        "title": "CC-CV current controller worked example",
        "text": "Use the defaults below with Highest cell voltage = 3.9 V, Charge-current magnitude limit = 2 A, Enable = 1 true / false. At 0 s, Signed current request (charge negative) is -1 A. Additional checks are listed below.",
        "url": "https://design.lemonergy.com/cosim.html?example=block-battery-cccv-controller",
        "label": "Open Studio example",
        "checks": [
          {
            "port": "request",
            "atS": 0,
            "value": -1,
            "tolerance": 1e-08,
            "label": "Signed current request (charge negative)",
            "unit": "A"
          }
        ],
        "inputs": [
          {
            "port": "voltage",
            "label": "Highest cell voltage",
            "value": 3.9,
            "unit": "V"
          },
          {
            "port": "limit",
            "label": "Charge-current magnitude limit",
            "value": 2,
            "unit": "A"
          },
          {
            "port": "enable",
            "label": "Enable",
            "value": 1,
            "unit": "true / false"
          }
        ]
      },
      "limits": [
        "This block generates a current request. The plant, actuator limits and loop stability must be modeled separately.",
        "The example verifies numerical behavior for synthetic parameters. Cell characterization and validation for an intended use are separate tasks."
      ],
      "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": [
        "astrom-murray-feedback",
        "tomaszewska-charging"
      ],
      "evidence": [
        "docs/glossary/native-block-verification.json"
      ],
      "sourceRepository": "Lemonergy Studio public contract",
      "sourceRevision": "verification-2026-10-27",
      "caseIds": [
        "native-battery-cccv-controller"
      ],
      "exampleTraces": [
        {
          "id": "battery-cccv-controller",
          "url": "https://lemonergy.com/learn/glossary/api/traces/battery-cccv-controller.json?v=8c62eaf84855",
          "title": "CC-CV current controller recorded example",
          "exampleId": "block-battery-cccv-controller",
          "source": "Executed synthetic Lemonergy Studio example",
          "recordedOn": "2026-10-28",
          "points": 11,
          "channels": 2,
          "omittedChannels": 0,
          "interpolation": "step",
          "solver": {
            "method": "dormand-prince-45",
            "reason": "no-continuous-states"
          }
        }
      ],
      "type": "battery-cccv-controller",
      "implementationId": "battery-cccv-controller",
      "url": "https://lemonergy.com/learn/glossary/blocks/battery-cccv-controller/",
      "documentationUrl": "https://lemonergy.com/learn/glossary/blocks/battery-cccv-controller/",
      "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=block-battery-cccv-controller"
        ]
      }
    }
  },
  "incoming": [
    {
      "id": "edge:usesBlock/native-battery-cccv-controller/0",
      "type": "usesBlock",
      "source": "workflow:native-battery-cccv-controller",
      "target": "block:battery-cccv-controller",
      "properties": {
        "sourceFile": "wiki-blocks.json",
        "position": 0,
        "name": "CC-CV current controller",
        "type": "battery-cccv-controller",
        "role": "Uses a PI voltage loop and an external current magnitude envelope to request charge current. Conditional integration limits windup while the request is saturated. Charging is negative in the discharge-positive current convention; disabling resets control memory.",
        "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:battery-cccv-controller/reference:astrom-murray-feedback",
      "type": "cites",
      "source": "block:battery-cccv-controller",
      "target": "reference:astrom-murray-feedback",
      "properties": {
        "sourceFile": "block-library.json",
        "scope": "Scientific or mathematical background; implementation scope is stated by the block contract"
      }
    },
    {
      "id": "edge:cites/block:battery-cccv-controller/reference:tomaszewska-charging",
      "type": "cites",
      "source": "block:battery-cccv-controller",
      "target": "reference:tomaszewska-charging",
      "properties": {
        "sourceFile": "block-library.json",
        "scope": "Scientific or mathematical background; implementation scope is stated by the block contract"
      }
    }
  ],
  "neighbors": [
    {
      "id": "workflow:native-battery-cccv-controller",
      "type": "Workflow",
      "label": "CC-CV current controller worked example",
      "properties": {
        "id": "native-battery-cccv-controller",
        "title": "CC-CV current controller worked example",
        "kind": "studio",
        "summary": "PI voltage regulation with an external current envelope and anti-windup.",
        "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": "Use the defaults below with Highest cell voltage = 3.9 V, Charge-current magnitude limit = 2 A, Enable = 1 true / false. At 0 s, Signed current request (charge negative) is -1 A. Additional checks are listed below.",
        "observe": "Inspect the outputs and numerical checks on the block reference page.",
        "limits": "This block generates a current request. The plant, actuator limits and loop stability must be modeled separately. The example verifies numerical behavior for synthetic parameters. Cell characterization and validation for an intended use are separate tasks.",
        "url": "https://design.lemonergy.com/cosim.html?example=block-battery-cccv-controller",
        "label": "Open Studio example",
        "evidence": [
          "docs/glossary/native-block-verification.json"
        ]
      }
    },
    {
      "id": "reference:astrom-murray-feedback",
      "type": "Reference",
      "label": "Feedback Systems: An Introduction for Scientists and Engineers, second edition",
      "properties": {
        "title": "Feedback Systems: An Introduction for Scientists and Engineers, second edition",
        "publisher": "Princeton University Press; author-maintained FBSwiki",
        "url": "https://fbswiki.org/wiki/index.php/Feedback_Systems%3A_An_Introduction_for_Scientists_and_Engineers",
        "type": "Textbook",
        "scope": "State-space modeling, feedback and PID control. These mathematical foundations do not establish a particular software implementation.",
        "year": 2021,
        "authors": [
          "Karl J. Åström",
          "Richard M. Murray"
        ],
        "accessed": "2026-10-27"
      }
    },
    {
      "id": "reference:tomaszewska-charging",
      "type": "Reference",
      "label": "Lithium-ion battery fast charging: A review",
      "properties": {
        "title": "Lithium-ion battery fast charging: A review",
        "publisher": "eTransportation",
        "url": "https://doi.org/10.1016/j.etran.2019.100011",
        "type": "Review article",
        "scope": "CC-CV and alternative charging protocols, transport limitations, degradation and thermal implications; results depend on cell and test conditions. Software behavior is documented separately in Lemonergy block references.",
        "year": 2019,
        "authors": [
          "Anna Tomaszewska et al."
        ],
        "accessed": "2026-10-27"
      }
    }
  ]
}