Add Core API for low-level pin control

Author: Jackhammer9

README.md

@@ -63,6 +63,7 @@
   * [Utilities](#utilities)
     * [sleep](#sleep)
     * [map](#map)
+  * [Core](#core)
 * [Supported Python features](#supported-python-features)
 * [License](#license)
 
@@ -483,6 +484,36 @@ mapped = map(512, 0, 1023, 0.0, 5.0)  # 2.5-ish
 print(mapped)
 ```
 
+### Core
+
+The **Core** module exposes low-level helpers that map directly to the Arduino
+API. Use these when you need to configure a pin or interact with a sensor that
+doesn't yet have a dedicated Reduino abstraction.
+
+| Helper | Description |
+| ------ | ----------- |
+| `pin_mode(pin, mode)` | Configure a pin for `INPUT`, `INPUT_PULLUP`, or `OUTPUT`. |
+| `digital_write(pin, value)` | Write `HIGH`/`LOW` to a digital pin. |
+| `analog_write(pin, value)` | Output a PWM value (0–255). |
+| `digital_read(pin)` | Read a digital pin (returns `0` or `1`). |
+| `analog_read(pin)` | Read an analogue value (0–1023 on most boards). |
+
+Constants `INPUT`, `OUTPUT`, `INPUT_PULLUP`, `HIGH`, and `LOW` mirror the
+Arduino macros so your code matches what you would write in C++.
+
+```python
+from Reduino import target
+target("COM3")
+
+from Reduino.Core import pin_mode, digital_write, digital_read, OUTPUT, HIGH, LOW
+
+pin_mode(7, OUTPUT)
+digital_write(7, HIGH)
+
+if digital_read(2) == HIGH:
+    digital_write(7, LOW)
+```
+
 ---
 
 ## Supported Python features

src/Reduino/Core/__init__.py

@@ -0,0 +1,87 @@
+"""Host-side stubs for the low-level Reduino Core helpers.
+
+These helpers provide a minimal in-memory simulation of the Arduino
+``pinMode``/``digitalWrite``/``analogWrite`` family so that importing
+``Reduino.Core`` succeeds when running documentation examples or unit tests
+on a host machine.  The transpiler recognises these names and replaces them
+with the corresponding Arduino calls during code generation.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Union
+
+__all__ = [
+    "pin_mode",
+    "digital_write",
+    "analog_write",
+    "digital_read",
+    "analog_read",
+    "INPUT",
+    "OUTPUT",
+    "INPUT_PULLUP",
+    "HIGH",
+    "LOW",
+]
+
+
+INPUT = "INPUT"
+OUTPUT = "OUTPUT"
+INPUT_PULLUP = "INPUT_PULLUP"
+HIGH = 1
+LOW = 0
+
+_PinKey = Union[int, str]
+
+_pin_modes: Dict[_PinKey, str] = {}
+_digital_values: Dict[_PinKey, int] = {}
+_analog_values: Dict[_PinKey, int] = {}
+
+
+def _normalise_pin(pin: _PinKey) -> _PinKey:
+    if isinstance(pin, str) and pin.isdigit():
+        return int(pin)
+    return pin
+
+
+def pin_mode(pin: _PinKey, mode: str) -> None:
+    """Record the configured ``mode`` for ``pin`` in the host simulation."""
+
+    key = _normalise_pin(pin)
+    _pin_modes[key] = mode
+    if mode == INPUT_PULLUP and key not in _digital_values:
+        _digital_values[key] = HIGH
+
+
+def digital_write(pin: _PinKey, value: Union[int, bool]) -> None:
+    """Store the logical ``value`` for ``pin`` in the host simulation."""
+
+    key = _normalise_pin(pin)
+    _digital_values[key] = HIGH if bool(value) else LOW
+
+
+def analog_write(pin: _PinKey, value: Union[int, float]) -> None:
+    """Store the PWM ``value`` (0-255) for ``pin`` in the host simulation."""
+
+    key = _normalise_pin(pin)
+    scaled = int(round(float(value)))
+    _analog_values[key] = max(0, min(255, scaled))
+
+
+def digital_read(pin: _PinKey) -> int:
+    """Return the previously stored logical value for ``pin``."""
+
+    key = _normalise_pin(pin)
+    if key in _digital_values:
+        return _digital_values[key]
+    if _pin_modes.get(key) == INPUT_PULLUP:
+        return HIGH
+    return LOW
+
+
+def analog_read(pin: _PinKey) -> int:
+    """Return the previously stored analogue value for ``pin``."""
+
+    key = _normalise_pin(pin)
+    return _analog_values.get(key, 0)
+

src/Reduino/transpile/parser.py

@@ -162,6 +162,8 @@ def _merge_element_types(types: List[str]) -> str:
     "abs": "int",
     "max": "int",
     "min": "int",
+    "digital_read": "int",
+    "analog_read": "int",
 }
 
 def _eval_const(expr: str, env: dict):
@@ -370,6 +372,40 @@ def _literal_length(node: ast.AST) -> Optional[int]:
                 return len(bound)
         return None
 
+    def _render_pin_argument(node: ast.AST) -> str:
+        expr = emit(node)
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            candidate = node.value.strip()
+            if candidate.isdigit():
+                return candidate
+            if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", candidate):
+                return candidate
+        return expr
+
+    def _call_argument(
+        call: ast.Call, position: int, keyword: Optional[str]
+    ) -> Optional[ast.AST]:
+        value: Optional[ast.AST] = None
+        has_positional = len(call.args) > position
+        has_keyword = False if keyword is None else any(
+            kw.arg == keyword for kw in call.keywords
+        )
+        if has_positional and has_keyword:
+            raise ValueError("duplicate argument provided")
+        if has_positional:
+            value = call.args[position]
+        elif has_keyword:
+            for kw in call.keywords:
+                if kw.arg == keyword:
+                    value = kw.value
+                    break
+        return value
+
+    def _ensure_allowed_keywords(call: ast.Call, allowed: Set[str]) -> None:
+        for kw in call.keywords:
+            if kw.arg not in allowed:
+                raise ValueError("unsupported keyword arguments in call")
+
     def emit(n: ast.AST) -> str:
         if isinstance(n, ast.Constant):
             if isinstance(n.value, bool):
@@ -695,6 +731,49 @@ def emit(n: ast.AST) -> str:
 
         if isinstance(n, ast.Call) and isinstance(n.func, ast.Name):
             fname = n.func.id
+            if fname == "pin_mode":
+                _ensure_allowed_keywords(n, {"pin", "mode"})
+                pin_node = _call_argument(n, 0, "pin")
+                mode_node = _call_argument(n, 1, "mode")
+                if pin_node is None or mode_node is None:
+                    raise ValueError("pin_mode requires pin and mode arguments")
+                pin_expr = _render_pin_argument(pin_node)
+                mode_expr = emit(mode_node)
+                return f"pinMode({pin_expr}, {mode_expr})"
+            if fname == "digital_write":
+                _ensure_allowed_keywords(n, {"pin", "value"})
+                pin_node = _call_argument(n, 0, "pin")
+                value_node = _call_argument(n, 1, "value")
+                if pin_node is None or value_node is None:
+                    raise ValueError(
+                        "digital_write requires pin and value arguments"
+                    )
+                pin_expr = _render_pin_argument(pin_node)
+                value_expr = emit(value_node)
+                return f"digitalWrite({pin_expr}, {value_expr})"
+            if fname == "analog_write":
+                _ensure_allowed_keywords(n, {"pin", "value"})
+                pin_node = _call_argument(n, 0, "pin")
+                value_node = _call_argument(n, 1, "value")
+                if pin_node is None or value_node is None:
+                    raise ValueError("analog_write requires pin and value arguments")
+                pin_expr = _render_pin_argument(pin_node)
+                value_expr = emit(value_node)
+                return f"analogWrite({pin_expr}, {value_expr})"
+            if fname == "digital_read":
+                _ensure_allowed_keywords(n, {"pin"})
+                pin_node = _call_argument(n, 0, "pin")
+                if pin_node is None:
+                    raise ValueError("digital_read requires a pin argument")
+                pin_expr = _render_pin_argument(pin_node)
+                return f"digitalRead({pin_expr})"
+            if fname == "analog_read":
+                _ensure_allowed_keywords(n, {"pin"})
+                pin_node = _call_argument(n, 0, "pin")
+                if pin_node is None:
+                    raise ValueError("analog_read requires a pin argument")
+                pin_expr = _render_pin_argument(pin_node)
+                return f"analogRead({pin_expr})"
             if fname == "str" and len(n.args) == 1 and not n.keywords:
                 return f"String({emit(n.args[0])})"
             if fname in {"int", "float"} and len(n.args) == 1 and not n.keywords:
@@ -1237,6 +1316,7 @@ def _merge_return_types(types: List[str], has_void: bool) -> str:
 RE_IMPORT_SLEEP   = re.compile(r"^\s*from\s+Reduino\.Utils\s+import\s+sleep\s*$")
 RE_IMPORT_SERIAL  = re.compile(r"^\s*from\s+Reduino\.Communication\s+import\s+SerialMonitor\s*$")
 RE_IMPORT_TARGET  = re.compile(r"^\s*from\s+Reduino\s+import\s+target\s*$")
+RE_IMPORT_CORE    = re.compile(r"^\s*from\s+Reduino\.Core\s+import\s+.*$")
 RE_IMPORT_ULTRASONIC = re.compile(r"^\s*from\s+Reduino\.Sensors\s+import\s+Ultrasonic\s*$")
 RE_IMPORT_BUTTON  = re.compile(r"^\s*from\s+Reduino\.Sensors\s+import\s+Button\s*$")
 RE_IMPORT_LCD     = re.compile(r"^\s*from\s+Reduino\.Displays\s+import\s+LCD\s*$")
@@ -3936,6 +4016,7 @@ def parse(src: str) -> Program:
             or RE_IMPORT_SLEEP.match(text)
             or RE_IMPORT_SERIAL.match(text)
             or RE_IMPORT_TARGET.match(text)
+            or RE_IMPORT_CORE.match(text)
             or RE_IMPORT_ULTRASONIC.match(text)
             or RE_IMPORT_BUTTON.match(text)
             or RE_IMPORT_POTENTIOMETER.match(text)

tests/test_emitter.py

@@ -35,6 +35,39 @@ def test_emit_generates_setup_and_loop(src, norm) -> None:
     assert "// no loop actions" in loop_section or loop_section.strip() == "{\n}\n"
 
 
+def test_emit_core_primitives(src, norm) -> None:
+    cpp = compile_source(
+        src(
+            """
+            from Reduino.Core import (
+                pin_mode,
+                digital_write,
+                analog_write,
+                digital_read,
+                analog_read,
+                INPUT,
+                OUTPUT,
+                HIGH,
+                LOW,
+            )
+
+            pin_mode(7, OUTPUT)
+            digital_write(7, HIGH)
+            analog_write(6, 42)
+            value = digital_read(5)
+            analog_value = analog_read(A0)
+            """
+        )
+    )
+
+    text = norm(cpp)
+    assert "pinMode(7, OUTPUT);" in text
+    assert "digitalWrite(7, HIGH);" in text
+    assert "analogWrite(6, 42);" in text
+    assert "value = digitalRead(5);" in text
+    assert "analog_value = analogRead(A0);" in text
+
+
 def test_emit_infinite_loop_moves_body_to_loop(src, norm) -> None:
     cpp = compile_source(
         src(

tests/test_parser.py

@@ -28,6 +28,7 @@
     ButtonPoll,
     ForRangeLoop,
     FunctionDef,
+    ExprStmt,
     LedDecl,
     LedOff,
     LedToggle,
@@ -135,6 +136,55 @@ def test_parser_handles_buzzer_primitives(src) -> None:
     assert melody.tempo == pytest.approx(180)
 
 
+def test_parser_supports_core_primitives(src) -> None:
+    code = src(
+        """
+        from Reduino.Core import (
+            pin_mode,
+            digital_write,
+            analog_write,
+            digital_read,
+            analog_read,
+            INPUT,
+            OUTPUT,
+            INPUT_PULLUP,
+            HIGH,
+            LOW,
+        )
+
+        pin_mode(7, OUTPUT)
+        digital_write(7, HIGH)
+        analog_write(6, 42)
+        value = digital_read(5)
+        analog_value = analog_read(A0)
+        """
+    )
+
+    program = _parse(code)
+
+    exprs = [
+        node.expr
+        for node in program.setup_body
+        if isinstance(node, ExprStmt)
+    ]
+    assert exprs[:3] == [
+        "pinMode(7, OUTPUT)",
+        "digitalWrite(7, HIGH)",
+        "analogWrite(6, 42)",
+    ]
+
+    assignments = [
+        node.expr
+        for node in program.setup_body
+        if isinstance(node, VarAssign)
+    ]
+    assert assignments == ["digitalRead(5)", "analogRead(A0)"]
+
+    decls = {decl.name: decl.c_type for decl in program.global_decls}
+    assert decls["value"] == "int"
+    assert decls["analog_value"] == "int"
+
+
 def test_parser_buzzer_optional_arguments(src) -> None:
     code = src(
         """