sim86 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
sim86/board.py ADDED
@@ -0,0 +1,422 @@
1
+ """Board files: a circuit (parts, wires, firmware per chip) as JSON.
2
+
3
+ See docs/circuits.md for the format. This module loads one, checks it
4
+ against the simulator's catalog and turns it into a run spec.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import re
11
+ from dataclasses import dataclass, field
12
+ from pathlib import Path
13
+ from typing import Any, Dict, List, Optional, Tuple, Union
14
+
15
+ from .api import Client, Sim86Error
16
+
17
+ PinRef = Tuple[str, str] # (part id, pin name)
18
+
19
+ _UNITS_MS = {"ns": 1e-6, "us": 1e-3, "µs": 1e-3, "ms": 1.0, "s": 1000.0, "m": 60_000.0, "min": 60_000.0}
20
+
21
+
22
+ def parse_ms(value: Union[str, int, float, None], what: str = "duration") -> Optional[float]:
23
+ """'250ms', '2s', '1.5m', 500 (ms) -> milliseconds."""
24
+ if value is None:
25
+ return None
26
+ if isinstance(value, (int, float)):
27
+ return float(value)
28
+ m = re.fullmatch(r"\s*([0-9]*\.?[0-9]+)\s*([a-zµ]*)\s*", str(value))
29
+ if not m or (m.group(2) or "ms") not in _UNITS_MS:
30
+ raise Sim86Error(f"{what} {value!r}: use a number of ms or e.g. '500ms', '2s', '1m'")
31
+ return float(m.group(1)) * _UNITS_MS[m.group(2) or "ms"]
32
+
33
+
34
+ _SI = {"p": 1e-12, "n": 1e-9, "u": 1e-6, "µ": 1e-6, "m": 1e-3, "": 1.0, "k": 1e3, "K": 1e3, "M": 1e6, "G": 1e9}
35
+ _UNITS = ("ohms", "ohm", "Ω", "R", "F", "V", "A", "Hz", "W", "s")
36
+
37
+
38
+ def parse_si(value: Union[str, int, float], what: str = "value") -> float:
39
+ """Schematic-style numbers: "4.7k", "4k7", "100n", "10uF", "3V3", "2.2MΩ", "5V", 330."""
40
+ if isinstance(value, (int, float)):
41
+ return float(value)
42
+ text = str(value).strip().replace(" ", "")
43
+ for unit in _UNITS:
44
+ if text.endswith(unit) and not re.fullmatch(r"[0-9.]+" + re.escape(unit) + r"[0-9]+", text):
45
+ text = text[: -len(unit)]
46
+ break
47
+ m = re.fullmatch(r"([0-9]*\.?[0-9]+)([pnuµmkKMG]?)", text)
48
+ if m:
49
+ return float(m.group(1)) * _SI[m.group(2)]
50
+ # 4k7 / 3V3 / 2R2 / 4u7: the letter is both the prefix and the decimal point
51
+ m = re.fullmatch(r"([0-9]+)([pnuµmkKMGVRF])([0-9]+)", text)
52
+ if m:
53
+ scale = 1.0 if m.group(2) in "VRF" else _SI[m.group(2)]
54
+ return float(f"{m.group(1)}.{m.group(3)}") * scale
55
+ raise Sim86Error(f"{what} {value!r}: write a number like 4.7k, 4k7, 100n, 10uF, 3V3 or 5V")
56
+
57
+
58
+ def resolve_config(config: Dict[str, Any], schema: Optional[Dict[str, Any]], label: str) -> Dict[str, Any]:
59
+ """Settings with schematic-style strings ("4.7k") turned into the numbers the part takes."""
60
+ props = (schema or {}).get("properties") or {}
61
+ out = dict(config)
62
+ for key, value in config.items():
63
+ types = props.get(key, {}).get("type")
64
+ types = types if isinstance(types, list) else [types]
65
+ if isinstance(value, str) and ("number" in types or "integer" in types):
66
+ number = parse_si(value, f"{label} config.{key}")
67
+ out[key] = int(round(number)) if "integer" in types and "number" not in types else number
68
+ return out
69
+
70
+
71
+ def parse_pin(ref: str) -> PinRef:
72
+ """'imu.SDA' -> ('imu', 'SDA'). The part id is everything before the first dot."""
73
+ if not isinstance(ref, str) or "." not in ref:
74
+ raise Sim86Error(f"pin {ref!r}: write it as <part id>.<pin>, e.g. \"imu.SDA\"")
75
+ part, pin = ref.split(".", 1)
76
+ if not part or not pin:
77
+ raise Sim86Error(f"pin {ref!r}: write it as <part id>.<pin>, e.g. \"imu.SDA\"")
78
+ return part, pin
79
+
80
+
81
+ @dataclass
82
+ class Part:
83
+ id: str
84
+ type: str
85
+ config: Dict[str, Any] = field(default_factory=dict)
86
+ firmware: Optional[Path] = None
87
+ label: Optional[str] = None # the schematic's reference designator, e.g. "R28", "U1 TCA6424A"
88
+ at: Optional[Tuple[float, float]] = None # where it sits on the live diagram
89
+
90
+
91
+ @dataclass
92
+ class Board:
93
+ path: Path
94
+ name: str
95
+ parts: List[Part]
96
+ wires: List[Tuple[PinRef, PinRef]]
97
+ limits: Dict[str, Any]
98
+ seed: Optional[int]
99
+ raw: Dict[str, Any]
100
+ wire_colors: Dict[int, str] = field(default_factory=dict) # wire index -> its colour on the diagram
101
+
102
+ def part(self, part_id: str) -> Part:
103
+ for p in self.parts:
104
+ if p.id == part_id:
105
+ return p
106
+ raise Sim86Error(f"no part {part_id!r} on {self.name}; parts: {', '.join(p.id for p in self.parts)}")
107
+
108
+ @property
109
+ def mcus(self) -> List[Part]:
110
+ return [p for p in self.parts if p.firmware is not None]
111
+
112
+
113
+ def _wire(entry: Any, i: int) -> Tuple[PinRef, PinRef]:
114
+ if isinstance(entry, list) and len(entry) == 2:
115
+ return parse_pin(entry[0]), parse_pin(entry[1])
116
+ if isinstance(entry, dict) and "from" in entry and "to" in entry:
117
+ return parse_pin(entry["from"]), parse_pin(entry["to"])
118
+ if isinstance(entry, dict) and {"source", "sourceHandle", "target", "targetHandle"} <= entry.keys():
119
+ # the SDK / editor circuit format
120
+ return (str(entry["source"]), str(entry["sourceHandle"])), (str(entry["target"]), str(entry["targetHandle"]))
121
+ raise Sim86Error(f"wires[{i}]: write a wire as [\"a.PIN\", \"b.PIN\"] or {{\"from\": …, \"to\": …}}")
122
+
123
+
124
+ def load_board(path: Union[str, Path], firmware_overrides: Optional[Dict[str, str]] = None) -> Board:
125
+ path = Path(path)
126
+ try:
127
+ raw = json.loads(path.read_text())
128
+ except OSError as e:
129
+ raise Sim86Error(f"can't read board file {path}: {e.strerror}") from None
130
+ except ValueError as e:
131
+ raise Sim86Error(f"{path} is not valid JSON: {e}") from None
132
+ if not isinstance(raw, dict):
133
+ raise Sim86Error(f"{path}: the board file must be a JSON object with \"parts\" and \"wires\"")
134
+
135
+ base = path.parent
136
+ overrides = firmware_overrides or {}
137
+ parts: List[Part] = []
138
+ seen = set()
139
+ for i, entry in enumerate(raw.get("parts", raw.get("components", []))):
140
+ if not isinstance(entry, dict) or "id" not in entry or "type" not in entry:
141
+ raise Sim86Error(f"parts[{i}]: every part needs an \"id\" and a \"type\"")
142
+ pid = str(entry["id"])
143
+ if "." in pid or not pid:
144
+ raise Sim86Error(f"parts[{i}]: id {pid!r} can't be empty or contain a dot")
145
+ if pid in seen:
146
+ raise Sim86Error(f"two parts have the id {pid!r}")
147
+ seen.add(pid)
148
+ fw = overrides.get(pid, entry.get("firmware"))
149
+ parts.append(Part(
150
+ id=pid,
151
+ type=str(entry["type"]),
152
+ config=dict(entry.get("config") or {}),
153
+ firmware=(base / fw) if fw and pid not in overrides else (Path(fw) if fw else None),
154
+ label=str(entry["label"]) if entry.get("label") else None,
155
+ at=(float(entry["at"][0]), float(entry["at"][1])) if entry.get("at") else None,
156
+ ))
157
+ for pid in overrides:
158
+ if pid not in seen:
159
+ raise Sim86Error(f"--firmware {pid}=…: there is no part {pid!r} on the board")
160
+ raw_wires = raw.get("wires", raw.get("connections", []))
161
+ wires = [_wire(w, i) for i, w in enumerate(raw_wires)]
162
+ wire_colors = {i: str(w["color"]) for i, w in enumerate(raw_wires) if isinstance(w, dict) and w.get("color")}
163
+ return Board(
164
+ path=path,
165
+ name=str(raw.get("name") or path.stem),
166
+ parts=parts,
167
+ wires=wires,
168
+ limits=dict(raw.get("limits") or {}),
169
+ seed=raw.get("seed"),
170
+ raw=raw,
171
+ wire_colors=wire_colors,
172
+ )
173
+
174
+
175
+ def _too_large(path: Path, limit: int, hint: str = "") -> Optional[str]:
176
+ size = path.stat().st_size
177
+ if size <= limit:
178
+ return None
179
+ return f"{path.name} is {size / 1024 / 1024:.1f} MB; the limit here is {limit // 1024 // 1024} MB.{hint}"
180
+
181
+
182
+ def _firmware_format_problem(path: Path, spec: Dict[str, Any]) -> Optional[str]:
183
+ formats = spec.get("formats") or []
184
+ with path.open("rb") as f:
185
+ head = f.read(4)
186
+ size = path.stat().st_size
187
+ is_elf = head == b"\x7fELF"
188
+ if "elf" in formats and is_elf:
189
+ return None
190
+ if "esp-merged-bin" in formats and head[:1] == b"\xe9" and size >= 64 * 1024:
191
+ return None
192
+ if "bin" in formats and not is_elf:
193
+ return None
194
+ if "hex" in formats and head[:1] == b":":
195
+ return None
196
+ if "uf2" in formats and head == b"UF2\n":
197
+ return None
198
+ return f"{path.name} is not a format this chip runs ({', '.join(formats)}). {spec.get('note', '')}".strip()
199
+
200
+
201
+ SCHEMA_PATH = ".sim86/board.schema.json"
202
+ # Firmware goes up with the run request; flash images are read back from the project.
203
+ MAX_FIRMWARE_BYTES = 24 * 1024 * 1024
204
+ MAX_FLASH_FILE_BYTES = 10 * 1024 * 1024
205
+ PIN_PATTERN = r"^[^.\s]+\.\S+$"
206
+
207
+
208
+ def board_schema(types: Optional[List[Dict[str, Any]]] = None) -> Dict[str, Any]:
209
+ """JSON Schema for board files, so editors explain each key, autocomplete
210
+ part types and flag mistakes while you type."""
211
+ type_schema: Dict[str, Any] = {
212
+ "type": "string",
213
+ "description": "Part type from the catalog (`sim86 parts`, `sim86 parts --show <type>`).",
214
+ }
215
+ if types:
216
+ type_schema["anyOf"] = [
217
+ {"const": t["type"], "description": f"{t.get('name', t['type'])} — {t.get('summary', '')}"}
218
+ for t in types
219
+ ] + [{"type": "string"}]
220
+ pin = {"type": "string", "pattern": PIN_PATTERN,
221
+ "description": "A pin as <part id>.<pin name>, e.g. \"mcu.D4\" or \"temp.SDA\"."}
222
+ time = {"type": ["string", "number"], "pattern": r"^\s*[0-9.]+\s*(ns|us|µs|ms|s|m|min)?\s*$",
223
+ "description": "\"250us\", \"5ms\", \"2s\", \"1m\", or a number of milliseconds."}
224
+ return {
225
+ "$schema": "http://json-schema.org/draft-07/schema#",
226
+ "title": "Simulator86 board",
227
+ "description": "Your hardware for Simulator86: parts, wires between their pins, and the firmware each chip runs.",
228
+ "type": "object",
229
+ "required": ["parts"],
230
+ "properties": {
231
+ "$schema": {"type": "string"},
232
+ "name": {"type": "string", "description": "Shown on the live page and in test output."},
233
+ "parts": {
234
+ "type": "array",
235
+ "description": "Every part on the board.",
236
+ "items": {
237
+ "type": "object",
238
+ "required": ["id", "type"],
239
+ "additionalProperties": False,
240
+ "properties": {
241
+ "id": {"type": "string", "pattern": r"^[^.\s]+$",
242
+ "description": "Your name for this part, no dots (\"mcu\", \"imu\", \"U3\"). Tests use it: board[\"imu\"]."},
243
+ "type": type_schema,
244
+ "label": {"type": "string", "description": "The schematic's name for it, e.g. \"R28\" or \"U1 TCA6424A\"."},
245
+ "at": {"type": "array", "items": {"type": "number"}, "minItems": 2, "maxItems": 2,
246
+ "description": "Where it sits on the live diagram: [x, y]. Parts without one are placed for you."},
247
+ "firmware": {"type": "string",
248
+ "description": "Chips only: the image this chip runs, relative to this file. "
249
+ "Format per chip: `sim86 parts --show <type>`."},
250
+ "config": {"type": "object",
251
+ "description": "Part settings; `sim86 parts --show <type>` lists them."},
252
+ },
253
+ },
254
+ },
255
+ "wires": {
256
+ "type": "array",
257
+ "description": "Each wire joins two pins. Pins joined through wires form one net.",
258
+ "items": {"oneOf": [
259
+ {"type": "array", "items": pin, "minItems": 2, "maxItems": 2},
260
+ {"type": "object", "required": ["from", "to"], "additionalProperties": False,
261
+ "properties": {"from": pin, "to": pin,
262
+ "color": {"type": "string", "description": "Its colour on the live diagram, e.g. \"#ef4444\"."}}},
263
+ ]},
264
+ },
265
+ "frames": {
266
+ "type": "array",
267
+ "description": "Titled frames drawn behind the parts on the live diagram, e.g. one per schematic sheet.",
268
+ "items": {"type": "object", "required": ["title", "x", "y", "width", "height"], "additionalProperties": False,
269
+ "properties": {"title": {"type": "string"}, "x": {"type": "number"}, "y": {"type": "number"},
270
+ "width": {"type": "number"}, "height": {"type": "number"}}},
271
+ },
272
+ "limits": {
273
+ "type": "object", "additionalProperties": False,
274
+ "description": "How long a run lasts.",
275
+ "properties": {
276
+ "duration": {**time, "description": "Simulated time to run. " + time["description"]},
277
+ "realtime": {**time, "description": "Wall-clock cap. " + time["description"]},
278
+ },
279
+ },
280
+ "seed": {"type": "integer", "description": "Same seed + same firmware = the same run, cycle for cycle."},
281
+ },
282
+ }
283
+
284
+
285
+ def check_board(board: Board, client: Client) -> List[str]:
286
+ """Everything that would stop this board from running, in plain words."""
287
+ problems: List[str] = []
288
+ by_id = {p.id: p for p in board.parts}
289
+ for p in board.parts:
290
+ entry = client.part(p.type)
291
+ label = f"{p.id} ({p.type})"
292
+ if entry is None:
293
+ problems.append(f"{label}: unknown part type — `sim86 parts {p.type}` lists close matches")
294
+ continue
295
+ takes_fw = bool(entry.get("firmware"))
296
+ if takes_fw and p.firmware is None:
297
+ problems.append(f"{label}: needs firmware — add \"firmware\": \"path/to/app.elf\"")
298
+ elif not takes_fw and p.firmware is not None:
299
+ problems.append(f"{label}: is not a chip that runs firmware; remove \"firmware\"")
300
+ elif p.firmware is not None and not p.firmware.is_file():
301
+ problems.append(f"{label}: firmware file not found: {p.firmware}")
302
+ elif p.firmware is not None:
303
+ problem = _firmware_format_problem(p.firmware, entry["firmware"]) or _too_large(
304
+ p.firmware,
305
+ MAX_FIRMWARE_BYTES,
306
+ " For an ELF, debug info is usually most of it: `arm-none-eabi-objcopy --strip-debug` keeps the symbols.",
307
+ )
308
+ if problem:
309
+ problems.append(f"{label}: {problem}")
310
+ for rel, local in flash_files(Board(board.path, board.name, [p], [], {}, None, {})) if p.config else []:
311
+ if not local.is_file():
312
+ problems.append(f"{label}: flashLayout file not found: {local}")
313
+ elif _too_large(local, MAX_FLASH_FILE_BYTES):
314
+ problems.append(f"{label}: flashLayout {_too_large(local, MAX_FLASH_FILE_BYTES)}")
315
+ schema = entry.get("config")
316
+ try:
317
+ resolve_config(p.config, schema, label)
318
+ except Sim86Error as e:
319
+ problems.append(str(e))
320
+ if p.config:
321
+ if not schema:
322
+ problems.append(f"{label}: takes no config")
323
+ else:
324
+ known = (schema.get("properties") or {}).keys()
325
+ for key in p.config:
326
+ if key not in known:
327
+ problems.append(f"{label}: no setting {key!r}; it takes {', '.join(known) or 'none'}")
328
+ for (a, b) in board.wires:
329
+ for pid, pin in (a, b):
330
+ part = by_id.get(pid)
331
+ if part is None:
332
+ problems.append(f"wire {a[0]}.{a[1]} → {b[0]}.{b[1]}: no part {pid!r}")
333
+ continue
334
+ entry = client.part(part.type)
335
+ if entry is None:
336
+ continue
337
+ names = [x["name"] for x in entry.get("pins", [])]
338
+ # A type this one replaced keeps its old pin names: the bare LED's
339
+ # A is the LED's +. The simulator moves the wire.
340
+ renamed = ((entry.get("legacy") or {}).get(part.type) or {}).get("pins") or {}
341
+ if pin not in names and renamed.get(pin) not in names:
342
+ problems.append(f"{pid} ({part.type}) has no pin {pin!r}; pins: {', '.join(names)}")
343
+ return problems
344
+
345
+
346
+ def flash_files(board: Board) -> List[Tuple[str, Path]]:
347
+ """Files a part's config.flashLayout programs into external flash, as
348
+ (path in the run's workspace, local file)."""
349
+ out = []
350
+ for p in board.parts:
351
+ for i, entry in enumerate((p.config or {}).get("flashLayout") or []):
352
+ rel = str(entry.get("file", "")).strip().lstrip("/")
353
+ if not rel:
354
+ raise Sim86Error(f"{p.id} config.flashLayout[{i}].file is empty")
355
+ out.append((rel, board.path.parent / rel))
356
+ return out
357
+
358
+
359
+ def upload_flash_files(board: Board, client: Client, project_id: str) -> None:
360
+ """Put flashLayout files where the simulator reads them; skipped when unchanged."""
361
+ import hashlib
362
+
363
+ from .api import config_lock, load_config, save_config
364
+
365
+ files = flash_files(board)
366
+ if not files:
367
+ return
368
+ # Parallel test workers on a first run: one uploads, the rest find it done.
369
+ with config_lock():
370
+ cfg = load_config()
371
+ sent = cfg.setdefault("flashUploads", {})
372
+ for rel, local in files:
373
+ data = local.read_bytes()
374
+ digest = hashlib.sha256(data).hexdigest()
375
+ key = f"{client.api_url}|{project_id}|{rel}"
376
+ if sent.get(key) == digest:
377
+ continue
378
+ client.put_project_file(project_id, rel, data)
379
+ sent[key] = digest
380
+ save_config(cfg)
381
+
382
+
383
+ def run_spec(board: Board, client: Client, project_id: str, *, duration_ms: Optional[float] = None,
384
+ realtime_ms: Optional[float] = None, scenario: Optional[Dict[str, Any]] = None,
385
+ seed: Optional[int] = None) -> Tuple[Dict[str, Any], Dict[str, bytes]]:
386
+ firmware: Dict[str, bytes] = {}
387
+ for p in board.mcus:
388
+ firmware[p.id] = p.firmware.read_bytes() # type: ignore[union-attr]
389
+ duration_ms = duration_ms if duration_ms is not None else parse_ms(board.limits.get("duration"), "limits.duration")
390
+ realtime_ms = realtime_ms if realtime_ms is not None else parse_ms(board.limits.get("realtime"), "limits.realtime")
391
+ limits: Dict[str, int] = {}
392
+ if duration_ms is not None:
393
+ limits["durationMs"] = int(duration_ms)
394
+ if realtime_ms is not None:
395
+ limits["realtimeMs"] = int(realtime_ms)
396
+ seed = seed if seed is not None else board.seed
397
+ spec: Dict[str, Any] = {
398
+ "projectId": project_id,
399
+ "components": [
400
+ {
401
+ "id": p.id,
402
+ "componentType": (client.part(p.type) or {}).get("type", p.type),
403
+ "config": resolve_config(p.config, (client.part(p.type) or {}).get("config"), p.id) or None,
404
+ **({"position": {"x": p.at[0], "y": p.at[1]}} if p.at else {}),
405
+ }
406
+ for p in board.parts
407
+ ],
408
+ "connections": [
409
+ {"source": a[0], "sourceHandle": a[1], "target": b[0], "targetHandle": b[1],
410
+ **({"color": board.wire_colors[i]} if i in board.wire_colors else {})}
411
+ for i, (a, b) in enumerate(board.wires)
412
+ ],
413
+ "limits": limits,
414
+ "streams": [],
415
+ }
416
+ if seed is not None:
417
+ spec["simulationSeed"] = int(seed)
418
+ if scenario:
419
+ spec["scenario"] = scenario
420
+ if board.raw.get("frames"):
421
+ spec["frames"] = board.raw["frames"]
422
+ return spec, firmware