knexflow 0.2.0__tar.gz

knexflow-0.2.0/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

knexflow-0.2.0/PKG-INFO

@@ -0,0 +1,431 @@
+Metadata-Version: 2.4
+Name: knexflow
+Version: 0.2.0
+Summary: Portable K'NEX Flow program library, controller compiler, and robotics SDK
+Author-email: siegzeon0079 <davidg0079@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/siegzeon0079/knexflow-rework
+Project-URL: Repository, https://github.com/siegzeon0079/knexflow-rework
+Project-URL: Issues, https://github.com/siegzeon0079/knexflow-rework/issues
+Keywords: knex,robotics,stem,education,usb-hid,blockly,compiler
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB) :: Human Interface Device (HID)
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: hid
+Requires-Dist: hidapi>=0.14; extra == "hid"
+Dynamic: license-file
+
+# K'NEX Flow Python library
+
+
+
+This package is a cross-platform library for editing K'NEX Flow program
+
+libraries, validating compiled-package JSON, and uploading compiled packages
+
+into stored controller slots. It requires Python 3.10 or later. Library and
+
+package validation use only the standard library.
+
+
+
+## Install
+
+
+
+From this directory:
+
+
+
+```powershell
+
+python -m pip install .
+
+```
+
+
+
+For USB HID uploads, install the optional `hidapi` backend:
+
+
+
+```powershell
+
+python -m pip install ".[hid]"
+
+```
+
+
+
+The HID backend depends on the operating system's USB HID permissions and
+
+driver configuration. The package does not require the vendor Windows desktop
+
+application for package validation or upload.
+
+
+
+## Command-line interface (`python -m knexflow_library` or `knexflow`)
+
+The CLI provides subcommands for bytecode disassembly, sound bundle management, hardware visualization, diagnostic reporting, backup management, and controller slot uploads:
+
+```powershell
+# 1. Disassemble controller bytecode (.knexpackage or compiled JSON):
+python -m knexflow_library disasm path\to\program.knexpackage
+python -m knexflow_library disasm path\to\program.json -o program.asm
+
+# 2. Inspect sound assets or extract audio payloads from .knexsound bundles / packages:
+python -m knexflow_library sounds path\to\robot_audio.knexsound
+python -m knexflow_library sounds path\to\robot_audio.knexsound -x extracted_sounds\
+
+# 3. Render hardware diagrams (terminal Unicode, SVG vector graphic, or HTML5 digital twin):
+python -m knexflow_library visualize path\to\program.json --format terminal
+python -m knexflow_library visualize path\to\program.json --format svg -o hardware.svg
+python -m knexflow_library visualize path\to\program.json --format html --show
+
+# 4. Analyze recorded telemetry runs and generate anomaly diagnostic reports:
+python -m knexflow_library diagnostics path\to\telemetry.json --format terminal
+python -m knexflow_library diagnostics path\to\telemetry.json --format markdown -o report.md
+python -m knexflow_library diagnostics path\to\telemetry.json --format html -o report.html
+
+# 5. Inspect and verify program library backups (legacy positional syntax also supported):
+python -m knexflow_library backup path\to\library-backup.json
+python -m knexflow_library backup path\to\library-backup.json --verify-only
+
+# 6. Upload compiled package to a stored controller slot (0-9):
+python -m knexflow_library upload path\to\compiled-package.json --slot 0 --yes
+```
+
+## Program library
+
+The version-1 JSON backup envelope remains compatible with the browser app:
+
+```powershell
+python -m knexflow_library path\to\library-backup.json
+python -m knexflow_library --verify-only path\to\library-backup.json
+```
+
+
+
+The API includes `create_text_program`, `create_blocks_program`,
+
+`update_program`, `duplicate_program`, `load_backup`, and `save_backup`.
+
+Program XML and source text remain user data; backup operations do not parse or
+
+execute either language.
+
+
+
+## Compiled packages and upload
+
+
+
+`CompiledProgram.from_manifest` validates the browser-compatible compiler JSON
+
+areas (base64 encoding, fixed area sizes, usable lengths, and sound directory
+
+checksums). A `ProgramUploader` accepts a validated package and a
+
+`ReportTransport`; it sends the HID download protocol to stored slots 0-9 and
+
+checks the controller's slot-presence response. A mock transport can be used
+
+for tests or alternative cross-platform HID implementations.
+
+
+
+To upload from the CLI, connect the controller and specify the target slot:
+
+
+
+```powershell
+
+python -m knexflow_library --upload-package path\to\compiled-package.json --slot 0
+
+```
+
+
+
+The command confirms before replacing a stored slot. `--yes` bypasses that
+
+prompt. Upload does **not** start or resume a program; starting remains outside
+
+the Python uploader API. Do not confuse a stored-slot upload with temporary
+
+development-program staging.
+
+
+
+## Compiler status
+
+
+
+The experimental pure-Python compiler supports linear Blockly charts and
+
+bounded `knex_repeat` blocks, expanded into linear actions, with numeric
+
+arithmetic expressions in `knex_wait`, constant-speed `knex_motor_run`, and
+
+single-motor `knex_motor_rotations`, plus optional
+
+`knex_motor_pair`, `knex_stop_motors` blocks targeting `all`, `knex_output_value` (TriLED channels 0 and 1; off, red, green, yellow, notset), and compile-time sensor configuration blocks `knex_sensor_led` and `knex_sensor_gain` (ports 1-6, LED ON/OFF, gain 0-2). Paired motors
+
+support independent ports, directions, and speeds, with continuous or
+
+rotation-limited actions. Rotation actions wait for the selected motors to
+
+finish. If a motor chart does not end in a stop-all block, a safety stop is
+
+appended, matching the official compiler. That compiler's generated safety
+
+stop also includes Port A when it was not selected; the Python output preserves
+
+that observed behavior.
+
+Literal rotation counts are limited to 0.1 to 1000.
+
+Supported expression operators are `+`, `-`, `*`, `/`, unary minus, and
+
+parentheses over numeric literals. Official wait, motor, arithmetic, rotation,
+
+coordinated-motor, bounded-repeat, numeric-variable, distance-conditional, sensor-configuration, display block, bounded while loop, and named procedure fixtures match
+
+byte-for-byte, including package header and code area when given each fixture
+
+timestamp. Other variable uses, sensor expressions, and chained
+
+same-precedence operators outside the vendor grammar are rejected. Repeat counts must be
+
+integer literals from 1 to 100, nested repeat depth is limited to 8, and
+
+expanded programs are limited to 250 blocks.
+
+
+
+Official reference fixtures and timestamp/volatile-byte notes are in
+
+`../tests/fixtures/compiler/`. Add a fixture and an exact Python comparison
+
+before extending the compiler with each new instruction family. Other variable
+
+constructs, sensor actions, other conditional forms, loops, procedures, sounds, and
+
+images are not implemented. Repeat blocks are statically expanded; they are
+
+not runtime loops. Conditional support is limited to one `knex_if_variable`,
+
+`knex_if_sensor_distance`, or `knex_if_boolean` (push-button) per chart. Numeric conditions may read assigned
+
+variables; distance conditions use a port from 1 to 6 and a numeric or
+
+previously assigned variable threshold in millimetres. Branches support waits,
+
+constant-speed motor runs, single-motor rotations, coordinated-motor
+
+actions, output values, and LCD display commands (clear LCD and print text on lines 0-3). Any chart with a motor branch must end with an explicit stop-all
+
+continuation; automatic branch safety stops and unverified motor action types
+
+are not implemented. Rotations use fixture-verified motor completion wait
+
+masks. Branch addresses are linked to fixture-verified native byte offsets.
+
+Unassigned-variable reads, sensor conditions other than distance and button, and
+
+nested/multiple conditionals are rejected. Push-button conditions use `button(port)`
+
+from ports 1 to 6 compared with 0 or 1 using `==` or `!=`. Distance conditions declare the
+
+selected sensor requirement. Current distance fixtures cover ports 1, 2, 3,
+
+4, 5, and 6; all six comparison operators; and literal, arithmetic,
+
+assigned-variable, and variable-arithmetic thresholds. The compiler supports numeric
+
+`knex_variable_set` assignments before the conditional, including reassignments
+
+and arithmetic that reads variables assigned earlier in the chart. Variables
+
+may also appear in either comparison expression. Reading an unassigned
+
+variable, assigning after the conditional, and assignments inside branches
+
+remain unsupported.
+
+
+
+## High-level controller API (`KnexBox`)
+
+For interactive or robotic scripting similar to PyTello, `knexflow_library.KnexBox` provides a fluent, object-oriented API for building and compiling controller programs:
+
+```python
+from knexflow_library import KnexBox
+
+box = KnexBox("Rover")
+box.motor("A", speed=50, direction="forward")
+box.wait(1.5)
+box.display_text(line=0, text="Moving...")
+box.stop_all()
+
+# Or with bounded while loops and variable assignments:
+box.assign("count", 3)
+with box.while_loop("count > 0", max_iterations=3):
+    box.motor("A", speed=40)
+    box.wait(1.0)
+    box.assign("count", "count - 1")
+
+# Or modular named procedures:
+box.call("step", times=2)
+box.wait(1.0)
+with box.procedure("step"):
+    box.motor("A", speed=50)
+    box.wait(0.5)
+    box.stop_all()
+
+# Compile to validated bytecode
+compiled = box.compile()
+
+# Upload directly to slot 0 over USB HID (requires knexflow_library[hid])
+# box.upload(slot=0)
+```
+
+## Hardware graphical representation (`knexflow_library.visual`)
+
+The library includes a zero-dependency hardware visualization submodule that renders the physical K'NEX Control Box, 4 motor ports (A–D with direction/speed), 6 sensor ports (1–6 with distance/button/color states), 2 TriLED channels, and the 4-line LCD screen:
+
+```python
+# 1. Console Unicode dashboard (instant view in PyCharm/terminal):
+print(box.hardware_dashboard())
+
+# 2. Export vector SVG graphic (previews directly in PyCharm):
+box.hardware_svg("rover_hardware.svg")
+
+# 3. Open interactive digital twin in the default web browser:
+box.show_hardware()
+
+# 4. Interactive execution timeline & step-by-step scrubber:
+print(box.timeline_dashboard())  # Terminal ASCII/Unicode table
+box.show_timeline()              # Browser player with Play/Pause and scrubber
+```
+
+## Sound asset management (`knexflow_library.packages`)
+
+The package subsystem provides official-compiler parity for inspecting, building, and packing compressed K'NEX sound assets (`131,072`-byte sound area):
+
+```python
+from knexflow_library import build_sound_area, parse_sound_area
+
+# Build a sound area from raw compressed audio payloads:
+area, length, checksum = build_sound_area([sound1_bytes, sound2_bytes])
+
+# Inspect individual sound directory entries and payloads:
+entries = parse_sound_area(area, length, checksum)
+for entry in entries:
+    print(f"Sound {entry.index}: {entry.length} bytes at [{entry.start_offset}:{entry.end_offset}]")
+
+# Attach sound assets to a KnexBox or compiled package:
+box.set_sounds([sound1_bytes, sound2_bytes])
+compiled = box.compile()
+print(compiled.sounds)           # Tuple of SoundDirectoryEntry
+sound_blobs = compiled.extract_sounds()
+
+# Export or import portable .knexsound bundles (zip archives with manifest):
+box.export_sound_bundle("robot_audio.knexsound")
+box.load_sound_bundle("robot_audio.knexsound")
+```
+
+## Telemetry replay bridge (`knexflow_library.visual`)
+
+Decode raw USB HID telemetry reports and replay recorded runs into the interactive digital twin:
+
+```python
+from knexflow_library.visual import TelemetryDecoder, replay_telemetry_to_timeline
+
+# Replay a recorded sequence of timestamped raw packets or telemetry dictionaries:
+timeline = box.replay_telemetry(recorded_packets, title="Diagnostic Run 5")
+print(timeline.render_dashboard())
+timeline.show()
+```
+
+## Offline diagnostic reporting (`knexflow_library.visual.diagnostics`)
+
+Analyze recorded controller sessions, detect hardware/interpreter anomalies (low battery, motor stalls, stop codes), and generate structured diagnostic reports in Markdown, HTML, or Terminal formats:
+
+```python
+from knexflow_library import analyze_telemetry, generate_diagnostic_report
+
+# 1. Quick terminal summary table:
+print(box.diagnostic_summary(telemetry_records))
+
+# 2. Export full Markdown or HTML report:
+box.generate_diagnostic_report(telemetry_records, output_path="diagnostic_run.md", format="markdown")
+box.generate_diagnostic_report(telemetry_records, output_path="diagnostic_run.html", format="html")
+```
+
+## Tone and melody generator (`knexflow_library.audio`)
+
+Compose musical tones and melodies similar to mBot / buzzer APIs with 12-TET note resolution (`C3`–`C6`), standard beat fraction timings (`whole`, `half`, `quarter`, `eighth`, `sixteenth`), and offline WAV generation:
+
+> [!NOTE]
+> **Hardware Compatibility**: The K'NEX Control Box firmware does not have a raw tone frequency generator opcode (official audio relies on opcode `0x0A OutputSound` pointing to compressed sound payloads in the ISD2130 chip sound area). Tones preview interactively in the browser timeline player (`box.show_timeline()`) and can be exported to standard WAV files (`generate_tone_wav`). When programs containing tone blocks are compiled to controller packages (`box.compile()`), tone blocks are lowered to equivalent duration pauses (`knex_wait`) to preserve package validity without sending unverified opcodes to the hardware.
+
+```python
+from knexflow_library import generate_tone_wav, generate_melody_wav
+
+# 1. Fluent box tone and melody programming:
+box.tone("C4", 0.5)                 # Play 261.63 Hz for 0.5s
+box.play_note("G4", "quarter")      # Play note G4 at current BPM (default 120 BPM = 0.5s)
+box.beep(880, 0.1)                  # Play quick 880 Hz beep
+box.play_melody([                   # Play sequenced melody
+    ("C4", "quarter"),
+    ("E4", "quarter"),
+    ("G4", "half"),
+    ("rest", "quarter"),
+], bpm=120)
+
+# 2. Offline audio synthesis to 16-bit PCM WAV (zero external dependencies):
+wav_data = generate_tone_wav("A4", duration_seconds=1.0)
+melody_wav = generate_melody_wav([("C4", "quarter"), ("G4", "half")], bpm=120)
+
+# 3. Interactive Web Audio preview:
+# Tones play back automatically via the browser Web Audio API in the timeline player:
+box.show_timeline()
+```
+
+## Bytecode disassembly inspection (`knexflow_library.disassembler`)
+
+Inspect compiled controller p-code with mnemonics, byte addresses, and parameter decoding:
+
+```python
+# 1. Disassemble directly from KnexBox:
+print(box.disassemble())
+
+# 2. Disassemble a compiled package or official fixture:
+compiled = box.compile()
+print(compiled.disassemble())
+```
+
+## Tests
+
+
+
+Run the standard-library tests from the repository root:
+
+
+
+```powershell
+
+python -m unittest discover -s tests\python -v
+
+```
+