|
| 1 | +## Custom JSON |
| 2 | + |
| 3 | +JSON is a human-readable file format for data storage, and it's what json2daisy 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. |
| 4 | + |
| 5 | +### JSON Basics |
| 6 | + |
| 7 | +For most hardware descriptions, there are only three JSON concepts you need to know: numbers, strings, and objects. |
| 8 | + |
| 9 | +#### Numbers and strings |
| 10 | + |
| 11 | +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. |
| 12 | + |
| 13 | +Text data is stored as "strings", which are strings of characters enclosed in double quote marks ("like this :O"). |
| 14 | + |
| 15 | +#### Objects |
| 16 | + |
| 17 | +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: |
| 18 | + |
| 19 | +```json |
| 20 | +{ "pin": 15 } |
| 21 | +``` |
| 22 | + |
| 23 | +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: |
| 24 | + |
| 25 | +```json |
| 26 | +{ |
| 27 | + "component": "Encoder", |
| 28 | + "pin": { |
| 29 | + "a": 12, |
| 30 | + "b": 11, |
| 31 | + "click": 0 |
| 32 | + } |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +An object with multiple pairs must have commas between each. |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +### Board description format |
| 41 | + |
| 42 | +To describe a board, your JSON will need an object with a few critical pairs: |
| 43 | + |
| 44 | +- name |
| 45 | + - This describes your project name and determines the names of automatically generated files |
| 46 | +- som |
| 47 | + - 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. |
| 48 | + - The exact strings are: |
| 49 | + - `"seed"` |
| 50 | + - `"patch_sm"` |
| 51 | +- audio |
| 52 | + - This is an object describing your audio layout. For most projects, this will simply have a single pair describing the number of audio channels: |
| 53 | +```json |
| 54 | +{ "channels": 2 } |
| 55 | +``` |
| 56 | +- components |
| 57 | + - 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: |
| 58 | + |
| 59 | +```json |
| 60 | +"components": { |
| 61 | + "myGateIn": { |
| 62 | + "component": "GateIn", |
| 63 | + "pin": 20 |
| 64 | + } |
| 65 | +} |
| 66 | +``` |
| 67 | + - More complicated objects may have more required fields. |
| 68 | + |
| 69 | +So, a very simple but viable board description might look like: |
| 70 | + |
| 71 | +```json |
| 72 | +{ |
| 73 | + "name": "MyProject", |
| 74 | + "som": "seed", |
| 75 | + "audio": { "channels": 2 }, |
| 76 | + "components": { |
| 77 | + "myGateIn": { |
| 78 | + "component": "GateIn", |
| 79 | + "pin": 20 |
| 80 | + } |
| 81 | + } |
| 82 | +} |
| 83 | + |
| 84 | +``` |
| 85 | + |
| 86 | +### Component reference |
| 87 | + |
| 88 | +| Type | _variant | Behavior | |
| 89 | +| --- | --- | --- | |
| 90 | +| **Inputs** | --- | --- | |
| 91 | +| 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. | |
| 92 | +| BipolarAnalogControl | --- | Similar to a regular analog control, but can handle negative voltages. | |
| 93 | +| Switch | --- | Returns a bang on the signal's rising edge (i.e. when the switch is actuated). | |
| 94 | +| Switch | _press | Returns a float representing the current state (1 = pressed, 0 = not pressed) | |
| 95 | +| Switch | _fall | Returns a bang on the signal's falling edge (i.e. when the switch is released). | |
| 96 | +| Switch | _seconds | Returns a float representing the number of seconds the switch has been held down. | |
| 97 | +| Switch3 | --- | Returns a float representing the current state, either 0 or 1. | |
| 98 | +| Encoder | --- | Returns a 1 if turned one direction, -1 if turned in the other, and 0 otherwise. | |
| 99 | +| Encoder | \_rise | Returns a bang when the encoder is pressed. The special alias _EncSwitch_ is always bound to this. | |
| 100 | +| Encoder | _press | Same as switch _press. | |
| 101 | +| Encoder | _fall | Same as switch _fall. | |
| 102 | +| Encoder | _seconds | Same as switch _seconds. | |
| 103 | +| GateIn | --- | Returns a float representing the current gate voltage, where a _high_ voltage is 1 and a _low_ voltage is 0. | |
| 104 | +| GateIn | _trig | Returns a bang on the rising edge of the gate signal. | |
| 105 | +| **Outputs** | --- | --- | |
| 106 | +| CVOuts | --- | Expects a floating point value from 0-1, usually converted to 0-5V. | |
| 107 | +| GateOut | --- | Expects a floating point value from 0-1. 0 sets the output low, and 1 sets it high. | |
| 108 | +| Led | --- | Expects a floating point value from 0-1. The brightness is PWM modulated to match the input. | |
| 109 | +| RgbLed | --- | Expects a floating point value from 0-1. The default behavior sets all three colors to the same brightness. | |
| 110 | +| RgbLed | _white | Same as default. | |
| 111 | +| RgbLed | _red | Expects a floating point value from 0-1. Sets the brightness of the red LED only. | |
| 112 | +| RgbLed | _green | Expects a floating point value from 0-1. Sets the brightness of the green LED only. | |
| 113 | +| RgbLed | _blue | Expects a floating point value from 0-1. Sets the brightness of the blue LED only. | |
| 114 | + |
| 115 | +### Built-in descriptions |
| 116 | + |
| 117 | +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. |
0 commit comments