hio-sdk 1.0.0__py3-none-any.whl

henglosio/sdk/__init__.py

@@ -0,0 +1,7 @@
+from .core.action import HIOAction, SUCCESS, FALLBACK
+from .core.trigger import HIOTrigger
+from .core.context import HIOContext
+from .core.stream import HIOStream, HIOStreamError
+from .core.registry import action, trigger
+from .core.identifier import generate_id
+from .core.clock import sleep_ms, ticks_ms, ticks_diff

henglosio/sdk/core/action.py

@@ -0,0 +1,54 @@
+from .context import HIOContext
+from .stream import HIOStream
+
+
+# Outputs an action can end on — execute() returns one of these, or the name
+# of one of its own custom outputs (see HIOAction.execute).
+SUCCESS = "success"
+FALLBACK = "fallback"
+
+
+class HIOAction:
+	# Base of every action. Subclass it, implement execute() and register the
+	# class with @action("<component>/<action>") (see registry.py):
+	#
+	#   @action("leds/set")
+	#   class SetLeds(HIOAction):
+	#
+	#       def initialize(self) -> None:
+	#           self.strip = Strip(pin=5)
+	#
+	#       async def execute(self, context) -> str:
+	#           self.strip.brightness(context.get("brightness"))
+	#           async for chunk in self.batch("leds"):
+	#               self.strip.write(chunk)
+	#           return SUCCESS
+	#
+	# One instance per action type, created the first time it runs and reused
+	# for every execution after that.
+
+	# Set by the runtime before each execute() — the same object execute()
+	# receives, kept here so helpers like batch() can reach it.
+	context: HIOContext
+
+	# Names of configs this action reads that a node may leave empty (an
+	# optional field). The runtime drops them from the run's values before
+	# each execution, so get() returns None instead of what an earlier action
+	# left under the same name.
+	clears = ()
+
+	def initialize(self) -> None:
+		# Called once, right after the instance is created. Optional.
+		pass
+
+	async def execute(self, context: HIOContext) -> "str | None":
+		# Runs the action. Returns the output it ended on: SUCCESS (or None),
+		# FALLBACK, or the name of a custom output. Values published with
+		# context.set() go back to the host and to the next actions.
+		raise NotImplementedError
+
+	def batch(self, name: str) -> HIOStream:
+		# The STREAM config `name`, arriving in chunks while this runs:
+		#   async for chunk in self.batch("leds"): ...
+		# See HIOStream for how long each chunk stays valid.
+		return self.context.stream(name)

henglosio/sdk/core/clock.py

@@ -0,0 +1,31 @@
+# Time for actions: MicroPython's millisecond clock and non-blocking sleep,
+# with CPython stand-ins so the same code runs under the host-side tests.
+#
+#   start = ticks_ms()
+#   await sleep_ms(250)                       # lets the rest of the runtime run
+#   elapsed = ticks_diff(ticks_ms(), start)   # wrap-safe
+#
+# ticks_ms() wraps around (on MicroPython after ~12.4 days): never compare or
+# subtract two of them directly — always through ticks_diff().
+
+import asyncio
+
+try:
+	from asyncio import sleep_ms                    # type: ignore  # MicroPython only
+except ImportError:
+	async def sleep_ms(ms: int) -> None:            # CPython (tests)
+		await asyncio.sleep(ms / 1000)
+
+try:
+	from time import ticks_ms, ticks_diff           # type: ignore  # MicroPython only
+except ImportError:
+	import time as _time
+
+	# Same period as MicroPython's ESP32 port (2^30), so wrap-around behaves alike.
+	_PERIOD = 1 << 30
+
+	def ticks_ms() -> int:                          # CPython (tests)
+		return int(_time.monotonic() * 1000) % _PERIOD
+
+	def ticks_diff(new: int, old: int) -> int:
+		return ((new - old + _PERIOD // 2) % _PERIOD) - _PERIOD // 2

henglosio/sdk/core/context.py

@@ -0,0 +1,52 @@
+from .stream import HIOStream
+
+class HIOContext:
+	# What an action sees while it runs.
+	#
+	# Values are MicroPython's own types — what the workflow calls integer,
+	# float, bool, string, list and object: int, float, bool, str, list, dict
+	# (and bytes for a file's or a color's raw bytes).
+
+	# The trigger whose branch the action runs in (its HIOTrigger instance) —
+	# None in Start's. Branches run side by side: an action answering its
+	# trigger (HTTP's Respond, its request) finds it here.
+	origin = None
+
+	def get(self, name: str) -> "int | float | bool | str | list | dict | bytes | None":
+		# The value of `name`: this action's own configs first, then whatever
+		# previous actions published, then the workflow variable `name`. A
+		# config bound to a variable already reads it here — the action never
+		# needs to know whether a value is a literal, a bind or a variable.
+		# None when there's no such value.
+		raise NotImplementedError
+
+	def set(self, name: str, value: "int | float | bool | str | list | dict | bytes") -> None:
+		# Publishes `value` under `name`: sent back to the host with this
+		# action's response and visible to the next actions (binds).
+		raise NotImplementedError
+
+	def remove(self, name: str) -> bool:
+		# Drops `name` from the values shared between the actions of the run.
+		# Variables aren't touched — see remove_variable.
+		raise NotImplementedError
+
+	def variable(self, name: str) -> "int | float | bool | str | list | dict | bytes | None":
+		# Only the workflow variable `name` (kept across loops of the program)
+		# — for when a config or output of the same name must not shadow it.
+		# None while it has no value.
+		raise NotImplementedError
+
+	def set_variable(self, name: str, value: "int | float | bool | str | list | dict | bytes") -> bool:
+		# Writes the workflow variable `name` — every action and script reads
+		# it from then on, across loops. False when there's no room for
+		# another variable (the workflow's MAX_VARIABLES).
+		raise NotImplementedError
+
+	def remove_variable(self, name: str) -> bool:
+		# The workflow variable `name` back to no value. False when it had none.
+		raise NotImplementedError
+
+	def stream(self, name: str) -> HIOStream:
+		# The STREAM config `name` — see HIOStream (HIOAction.batch is the
+		# shortcut for this).
+		raise NotImplementedError

henglosio/sdk/core/identifier.py

@@ -0,0 +1,15 @@
+# 16-bit id of a name (config, output, "<component>/<action>") — the same hash
+# as @henglosio/workflow's generateId (src/utils/identifier.ts), which is what
+# the host puts on the wire. Keep the two identical.
+def generate_id(name: str) -> int:
+	hash = 0x811C
+	for byte in name.encode():
+		hash ^= byte
+		hash = (hash * 0x0101) & 0xFFFF
+	return hash
+
+
+def variable_id(name: str) -> int:
+	# VARIABLE_ID of a workflow variable — @henglosio/workflow's
+	# computeWireVariableId. Case-insensitive, like the studio's names.
+	return generate_id("var/" + name.lower())

henglosio/sdk/core/registry.py

@@ -0,0 +1,67 @@
+from .action import HIOAction
+from .trigger import HIOTrigger
+from .identifier import generate_id
+
+
+# ACTION_ID -> action (or trigger) class. ACTION_ID is
+# generate_id("<component>/<action>"), the same id the host puts in every EXECUTE.
+_actions = {}
+
+
+def action(name: str):
+	# Class decorator registering an action under "<component>/<action>":
+	#
+	#   @action("leds/set")
+	#   class SetLeds(HIOAction): ...
+	#
+	# Rejects, at import time, a class that doesn't inherit HIOAction or
+	# doesn't implement execute() — MicroPython has no abc to do it for us.
+	def register(cls):
+
+		if not issubclass(cls, HIOAction):
+			raise TypeError("@action('%s'): %s must inherit from HIOAction" % (name, cls.__name__))
+
+		if cls.execute is HIOAction.execute:
+			raise TypeError("@action('%s'): %s must implement execute()" % (name, cls.__name__))
+
+		_actions[generate_id(name)] = cls
+		return cls
+
+	return register
+
+
+def trigger(name: str):
+	# Class decorator registering a trigger under "<component>/<trigger>" —
+	# in the same id space as actions: its node's EXECUTE carries this id, and
+	# the runtime arms it instead of running it (see TriggerService).
+	#
+	#   @trigger("http/request trigger")
+	#   class RequestTrigger(HIOTrigger): ...
+	def register(cls):
+
+		if not issubclass(cls, HIOTrigger):
+			raise TypeError("@trigger('%s'): %s must inherit from HIOTrigger" % (name, cls.__name__))
+
+		if cls.poll is HIOTrigger.poll:
+			raise TypeError("@trigger('%s'): %s must implement poll()" % (name, cls.__name__))
+
+		_actions[generate_id(name)] = cls
+		return cls
+
+	return register
+
+
+def is_trigger(action_id: int) -> bool:
+	# Whether the class registered under `action_id` is a trigger.
+	cls = _actions.get(action_id)
+	return cls is not None and issubclass(cls, HIOTrigger)
+
+
+def find(action_id: int):
+	# The action class registered under `action_id`, or None.
+	return _actions.get(action_id)
+
+
+def unregister(action_id: int) -> None:
+	# Forgets the class under `action_id` — its component was removed.
+	_actions.pop(action_id, None)

henglosio/sdk/core/stream.py

@@ -0,0 +1,56 @@
+class HIOStreamError(Exception):
+	# The stream ended before all its data arrived: timeout, an invalid chunk,
+	# or the host gave up.
+	pass
+
+
+class HIOStream:
+	# A config whose value arrives in chunks while the action is already
+	# running, instead of inside the EXECUTE — for values too big for one frame
+	# (e.g. the state of every LED in a strip). Consumed with `async for`:
+	#
+	#   async def execute(self, ctx):
+	#       async for chunk in self.batch("leds"):
+	#           self.strip.write(chunk)
+	#
+	# Each chunk is a memoryview holding a whole number of `data_type`
+	# elements. It's only valid until the loop asks for the next one — copy
+	# with bytes(chunk) anything that must outlive that. The host only sends
+	# the next chunk after this one is consumed, so a slow loop body slows the
+	# host down instead of losing data. While the action waits for a chunk,
+	# nothing else runs on the board.
+	#
+	# The loop ends normally after the last chunk (TOTAL_SIZE bytes, or the
+	# empty end chunk of an open-ended stream), or raises HIOStreamError.
+	# A stream can be read once.
+
+	config_id: int
+	data_type: int          # DataType — chunks hold whole values of it (a byte of a sized one)
+	total_size: int         # bytes across every chunk — 0 when open-ended
+	received: int           # bytes delivered so far
+
+	def __aiter__(self) -> "HIOStream":
+		return self
+
+	async def __anext__(self) -> memoryview:
+		raise NotImplementedError
+
+	async def read(self) -> bytearray:
+		# The whole value at once, for one that fits in RAM:
+		#   data = await self.batch("text").read()
+		# Filled in place into a buffer sized from TOTAL_SIZE up front — no
+		# reallocation per chunk. An open-ended stream has no size to start
+		# from, so it grows as chunks arrive.
+		if not self.total_size:
+			data = bytearray()
+			async for chunk in self:
+				data.extend(chunk)
+			return data
+
+		data = bytearray(self.total_size)
+		view = memoryview(data)
+		offset = 0
+		async for chunk in self:
+			view[offset:offset + len(chunk)] = chunk
+			offset += len(chunk)
+		return data

henglosio/sdk/core/trigger.py

@@ -0,0 +1,55 @@
+from .context import HIOContext
+
+
+class HIOTrigger:
+	# Base of every trigger — a node that starts a branch of the flow when
+	# something happens (a request comes in, a pin changes, a code is
+	# received), instead of being reached by a wire. Subclass it, implement
+	# poll() and register the class with @trigger("<component>/<trigger>"):
+	#
+	#   @trigger("ir/code trigger")
+	#   class CodeTrigger(HIOTrigger):
+	#
+	#       def arm(self, context) -> None:
+	#           self.receiver = Receiver(context.get("code trigger/rx pin"))
+	#
+	#       def poll(self, context) -> bool:
+	#           code = self.receiver.code()
+	#           if code is None:
+	#               return False
+	#           context.set("code", code)
+	#           return True
+	#
+	# One instance per trigger NODE (two Timers are two instances, each with
+	# its own configs), created when the program arms it. The runtime runs one
+	# branch at a time: while a branch runs, an event waits in the trigger
+	# itself (a pin's edge flag, a request in the socket's queue) until poll()
+	# is asked again.
+
+	# Set by the runtime before each call — the same object the call receives.
+	context: HIOContext
+
+	def initialize(self) -> None:
+		# Called once, right after the instance is created. Optional.
+		pass
+
+	def arm(self, context: HIOContext) -> None:
+		# The program starts listening: read the configs (context.get), open
+		# what it listens on (a socket, an IRQ). Called again when the host
+		# re-arms it with other configs — after disarm(). Optional.
+		pass
+
+	def poll(self, context: HIOContext) -> bool:
+		# Whether it fired since the last call — publishing what happened with
+		# context.set(), which the branch's actions read like any output.
+		# Must NOT block: it's asked over and over while the board is idle.
+		raise NotImplementedError
+
+	def finish(self, context: HIOContext) -> None:
+		# The branch it started is over (its last action had nothing wired
+		# after it) — e.g. answer a request nobody answered. Optional.
+		pass
+
+	def disarm(self) -> None:
+		# Stop listening: close what arm() opened. Optional.
+		pass

henglosio/sdk/testing.py

@@ -0,0 +1,98 @@
+import asyncio
+
+from .core.action import HIOAction
+from .core.context import HIOContext
+from .core.stream import HIOStream, HIOStreamError
+
+# Runs an action without the runtime — in a component's unit tests, or by hand
+# on the board's REPL:
+#
+#   from henglosio.sdk.testing import MemoryContext, run
+#   from components.http.request import RequestAction
+#
+#   ctx = MemoryContext({"request/method": "GET", "request/url": "https://example.com"})
+#   run(RequestAction, ctx)       # -> "ok"
+#   ctx.published                 # {"status": 200, "body": "...", ...}
+#
+# Values go in as an action receives them from the runtime: a string or
+# options config as a str, an integer config as an int, a float config as a
+# float, a toggle as a bool, a list / object as a list / dict, a file as
+# bytes. Nothing imports this module at runtime — it only costs what a test
+# that uses it loads.
+
+
+class MemoryStream(HIOStream):
+	# A STREAM config whose whole value is already here: handed out in chunks
+	# of `chunk_size` bytes, like the host would send them. Read once.
+
+	def __init__(self, data: "bytes | bytearray", chunk_size: int = 64, data_type: int = 0) -> None:
+		self._data = bytes(data)
+		self._chunk_size = max(1, chunk_size)
+		self.config_id = 0
+		self.data_type = data_type
+		self.total_size = len(self._data)
+		self.received = 0
+
+	async def __anext__(self) -> memoryview:
+		if self.received >= self.total_size:
+			raise StopAsyncIteration
+		chunk = memoryview(self._data)[self.received:self.received + self._chunk_size]
+		self.received += len(chunk)
+		return chunk
+
+
+class MemoryContext(HIOContext):
+	# An HIOContext over plain dicts, looked up like the runtime's
+	# ActionContext: `values` (the configs given, and what the action
+	# published — set() replaces a config of the same name) first, then the
+	# workflow `variables`. What the action published is in `published`.
+
+	def __init__(self, configs: "dict | None" = None, variables: "dict | None" = None, streams: "dict | None" = None) -> None:
+		self.values = dict(configs or {})
+		self.variables = dict(variables or {})
+		# name -> the stream's bytes (or a MemoryStream, for its own chunk size).
+		self.streams = dict(streams or {})
+		self.published = {}
+
+	def get(self, name: str):
+		if name in self.values:
+			return self.values[name]
+		return self.variables.get(name)
+
+	def set(self, name: str, value) -> None:
+		self.values[name] = value
+		self.published[name] = value
+
+	def variable(self, name: str):
+		return self.variables.get(name)
+
+	def set_variable(self, name: str, value) -> bool:
+		self.variables[name] = value
+		return True
+
+	def remove_variable(self, name: str) -> bool:
+		return self.variables.pop(name, None) is not None
+
+	def remove(self, name: str) -> bool:
+		# Like the runtime: the run's values only, never a variable.
+		return self.values.pop(name, None) is not None
+
+	def stream(self, name: str) -> HIOStream:
+		value = self.streams.get(name)
+		if value is None:
+			raise HIOStreamError("'%s' is not a STREAM config of this execution" % name)
+		if not isinstance(value, HIOStream):
+			value = self.streams[name] = MemoryStream(value)
+		return value
+
+
+def run(action: "type | HIOAction", context: "MemoryContext | None" = None) -> "str | None":
+	# Runs `action` once with `context` (an empty one when left out) and
+	# returns the output it ended on. A class gets an instance, initialized
+	# like the runtime does the first time; an instance is reused as it is.
+	if isinstance(action, type):
+		action = action()
+		action.initialize()
+	context = context if context is not None else MemoryContext()
+	action.context = context
+	return asyncio.run(action.execute(context))

hio_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: hio-sdk
+Version: 1.0.0
+Summary: SDK for writing HenglosIO component actions and triggers in MicroPython.
+Keywords: henglosio,micropython,iot,sdk
+Author: Henglos
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# hio-sdk
+
+The SDK HenglosIO components are written with: the base classes and decorators
+for actions and triggers (`from henglosio.sdk import HIOAction, action, ...`), plus
+`henglosio.sdk.testing` to run an action under pytest without a board.
+
+```sh
+pip install hio-sdk
+```
+
+The same code runs on the board: every `@henglosio/hio-system` release ships
+the sdk inside it, so a component never installs it on the device. This package
+is for writing and testing components on your machine (types, autocomplete,
+`henglosio.sdk.testing`).
+
+## License
+
+Part of Henglos IO, distributed under the [Sustainable Use License](LICENSE).

hio_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+henglosio/sdk/__init__.py,sha256=M1GLdcmrhr851YW7THFBje5qmvzqcNn1VzSXxieTYVg,325
+henglosio/sdk/core/action.py,sha256=_pG_LGQLN0hO9zUXnr3MgTngBsjzYS6a1eIZLFGjPqo,2010
+henglosio/sdk/core/clock.py,sha256=ph_a97f9Nin8K0Agm6NoKxrMNZx2t8MrfG8HLHRiHmw,1174
+henglosio/sdk/core/context.py,sha256=G3jXoFH4_BP0cWlff5QFdZ4XThHTtVTzmWqoHRkAqZQ,2385
+henglosio/sdk/core/identifier.py,sha256=tpls-S4ubpJZ_s3ZHuSLZwGewsiTzGeouQSMKa4vM1Y,581
+henglosio/sdk/core/registry.py,sha256=KukFdBHq_BShkyx_LONp5rGx76k1UiE8LiBZYa3SoMw,2095
+henglosio/sdk/core/stream.py,sha256=U5KoM4-JnK4qYVjyM1ELNhcp_hRmAB5iovtiQIhQKqk,2116
+henglosio/sdk/core/trigger.py,sha256=U7AJWXRw92FiEGAYtbOnnma7Xl_RsnpFDJOnMM8G_z0,2145
+henglosio/sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+henglosio/sdk/testing.py,sha256=FAZ978J14_liUzhzo8G6VmvrOh08nZGTnB1DA_DnumQ,3652
+hio_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=psVVsuL8XpB9Tsr0gg6MZ7p58oD_mMhgcr8CPTBBCKk,4080
+hio_sdk-1.0.0.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
+hio_sdk-1.0.0.dist-info/METADATA,sha256=q17H9u2tHZFbszXpE4GxEBd1LZaqeFnyDTWp3dKHkDY,903
+hio_sdk-1.0.0.dist-info/RECORD,,

hio_sdk-1.0.0.dist-info/WHEEL

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

hio_sdk-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,80 @@
+# Sustainable Use License
+
+Version 1.0
+
+Copyright (c) 2026 Henglos — the licensor of Henglos IO.
+
+Henglos IO is fair-code: these terms let you use and modify it for your own or your company's
+internal use, and share it free of charge for non-commercial purposes. Any other use — selling it,
+or offering it to others as a paid product or service — needs a separate commercial agreement with
+the licensor.
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+## Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+## Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.