integrate json2daisy into hvcc (#307)

* integrate json2daisy into hvcc

* drop wstd2daisy dependency; update changelog

* fix package resource path

* cleanup

Author: dromer

CHANGELOG.md

@@ -19,6 +19,11 @@ Bugfixes:
 * c2dpf: portGroup template fix with i/o port 0 as CV
 * c2wwise: use correct SDK header paths and allow any platform in the xml - thanks to @eu-ch
 
+Updates:
+
+* drop py3.8 - add py3.13
+* integrate json2daisy library, tests and documentation
+
 0.13.4
 -----
 

docs/03.gen.daisy.components.md

@@ -0,0 +1,117 @@
+## Custom JSON
+
+JSON is a human-readable file format for data storage, and it's what plugdata uses to help translate your Pd patch into something that will run on a Daisy-based board. If you haven't worked with something like it before, it might look a little strange, but don't worry! We'll cover enough here to get you on your way to custom hardware in no time.
+
+### JSON Basics
+
+For most hardware descriptions, there are only three JSON concepts you need to know: numbers, strings, and objects.
+
+#### Numbers and strings
+
+Numbers are just numbers! They can be integers (1, 2, 3) or any real number (3.141), and don't need any special formatting or indication.
+
+Text data is stored as "strings", which are strings of characters enclosed in double quote marks ("like this :O").
+
+#### Objects
+
+An object is a set of _name_, _value_ pairs, enclosed in curly brackets. Each name is a unique string, and each value can be a number, a string, or another object. The name and value are separated by a colon. For a simple object, you might just have one name with a simple value:
+
+```json
+{ "pin": 15 }
+```
+
+When things get a little more complicated, such as objects with mutliple pairs, the pairs are usually broken up into their own lines for readability:
+
+```json
+{
+    "component": "Encoder",
+    "pin": {
+        "a": 12,
+        "b": 11,
+        "click": 0
+    }
+}
+```
+
+An object with multiple pairs must have commas between each.
+
+To make editing JSON by hand easy, it's usually best to use a program that provides syntax highlighting (like the colors you see on this page). [VS Code](https://code.visualstudio.com/) is a great cross-platform tool for this. Of course, you can just use a normal text editor, but errors may be more difficult to spot, and some may even mangle the text in undesireable ways.
+
+### Board description format
+
+To describe a board, your JSON will need an object with a few critical pairs:
+
+- name
+  - This describes your project name and determines the names of automatically generated files
+- som
+  - This is the SOM (system-on-module) that your project uses. This will usually be the Daisy Seed, but can also be the Patch SM.
+  - The exact strings are:
+    - `"seed"`
+    - `"patch_sm"`
+- audio
+    - This is an object describing your audio layout. For most projects, this will simply have a single pair describing the number of audio channels:
+```json
+{ "channels": 2 }
+```
+- components
+  - This is the meat of your description. Here, you'll describe all the input and output components of your design such as knobs, CVs, LEDs, and so on. The name determines the receive or send name in your Pd patch, and must have an object with a `"component"` name. For example, a gate input could be described as:
+
+```json
+"components": {
+    "myGateIn": {
+        "component": "GateIn",
+        "pin": 20
+    }
+}
+```
+  - More complicated objects may have more required fields.
+
+So, a very simple but viable board description might look like:
+
+```json
+{
+    "name": "MyProject",
+    "som": "seed",
+    "audio": { "channels": 2 },
+    "components": {
+        "myGateIn": {
+            "component": "GateIn",
+            "pin": 20
+        }
+    }
+}
+
+```
+
+### Component reference
+
+| Type | _variant | Behavior |
+| --- | --- | --- |
+| **Inputs** | --- | --- |
+| AnalogControl | --- | Returns a floating point representation of the voltage at its input. The typical range is 0-5 V, which is represented as 0-1. |
+| BipolarAnalogControl | --- | Similar to a regular analog control, but can handle negative voltages. |
+| Switch | --- | Returns a bang on the signal's rising edge (i.e. when the switch is actuated). |
+| Switch | _press | Returns a float representing the current state (1 = pressed, 0 = not pressed) |
+| Switch | _fall | Returns a bang on the signal's falling edge (i.e. when the switch is released). |
+| Switch | _seconds | Returns a float representing the number of seconds the switch has been held down. |
+| Switch3 | --- | Returns a float representing the current state, either 0 or 1. |
+| Encoder | --- | Returns a 1 if turned one direction, -1 if turned in the other, and 0 otherwise. |
+| Encoder | \_rise | Returns a bang when the encoder is pressed. The special alias _EncSwitch_ is always bound to this. |
+| Encoder | _press | Same as switch _press. |
+| Encoder | _fall | Same as switch _fall. |
+| Encoder | _seconds | Same as switch _seconds. |
+| GateIn | --- | Returns a float representing the current gate voltage, where a _high_ voltage is 1 and a _low_ voltage is 0. |
+| GateIn | _trig | Returns a bang on the rising edge of the gate signal. |
+| **Outputs** | --- | --- |
+| CVOuts | --- | Expects a floating point value from 0-1, usually converted to 0-5V. |
+| GateOut | --- | Expects a floating point value from 0-1. 0 sets the output low, and 1 sets it high. |
+| Led | --- | Expects a floating point value from 0-1. The brightness is PWM modulated to match the input. |
+| RgbLed | --- | Expects a floating point value from 0-1. The default behavior sets all three colors to the same brightness. |
+| RgbLed | _white | Same as default. |
+| RgbLed | _red | Expects a floating point value from 0-1. Sets the brightness of the red LED only. |
+| RgbLed | _green | Expects a floating point value from 0-1. Sets the brightness of the green LED only. |
+| RgbLed | _blue | Expects a floating point value from 0-1. Sets the brightness of the blue LED only. |
+
+### Built-in descriptions
+
+If some details are still unclear, the [JSON descriptions for the built-in boards](https://github.com/Wasted-Audio/hvcc/tree/develop/hvcc/generators/c2daisy/json2daisy/resources) might help.

docs/03.gen.daisy.md

@@ -20,7 +20,7 @@ Which can be configured using the `-m` metadata.json `daisy.board` setting:
 }
 ```
 
-However one can also create custom board layouts. See [the Electro-Smith documentation](https://github.com/electro-smith/DaisyWiki/wiki/Pd2dsy-Guide) for more information.
+However one can also create custom board layouts. See [the Daisy Component documentation](03.gen.daisy.components.md) for more information.
 
 The custom layout can be passed on via the meta.json as such:
 
@@ -112,4 +112,4 @@ The linker and `APP_TYPE` can be set in the json metadata accordingly:
         "bootloader": <APP_TYPE>
     }
 }
-```
+```

hvcc/generators/c2daisy/c2daisy.py

@@ -2,12 +2,12 @@
 import os
 import shutil
 import time
-import json2daisy  # type: ignore
 
 from typing import Any, Dict, Optional
 
 from ..copyright import copyright_manager
-from . import parameters
+from .parameters import parse_parameters
+from .json2daisy import generate_header_from_file, generate_header_from_name
 
 from hvcc.interpreters.pd2hv.NotificationEnum import NotificationEnum
 from hvcc.types.compiler import Generator, CompilerResp, CompilerNotif, CompilerMsg, ExternInfo
@@ -67,15 +67,15 @@ def compile(
             shutil.copytree(c_src_dir, source_dir)
 
             if daisy_meta.board_file is not None:
-                header, board_info = json2daisy.generate_header_from_file(daisy_meta.board_file)
+                header, board_info = generate_header_from_file(daisy_meta.board_file)
             else:
-                header, board_info = json2daisy.generate_header_from_name(board)
+                header, board_info = generate_header_from_name(board)
 
             # remove heavy out params from externs
             externs.parameters.outParam = [
                 t for t in externs.parameters.outParam if not any(x == y for x in hv_midi_messages for y in t)]
 
-            component_glue = parameters.parse_parameters(
+            component_glue = parse_parameters(
                 externs.parameters, board_info['components'], board_info['aliases'], 'hardware')
             component_glue['class_name'] = board_info['name']
             component_glue['patch_name'] = patch_name

hvcc/generators/c2daisy/json2daisy/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Electrosmith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hvcc/generators/c2daisy/json2daisy/__init__.py

@@ -0,0 +1 @@
+from .json2daisy import *  # noqa