Merge pull request #159 from scanner-darkly/grid2

teletype 3.0

CHANGELOG.md

@@ -1,9 +1,36 @@
 # Changelog
 
-## v2.NEXT
+## v3.0
+
+- **NEW**: grid integration / grid visualizer / grid control mode
+- **NEW**: multiline copy/paste and editing
+- **NEW**: new keybindings to move by words
+- **NEW**: undo in script editing
+- **NEW**: i2c support for ER-301
+- **NEW**: i2c support for 16n Faderbank
+- **NEW**: i2c support for Matrixarchate
+- **NEW**: i2c support for W/
+- **NEW**: new op: ?
+- **NEW**: new ops: P.MIN, PN.MIN, P.MAX, PN.MAX, P.RND, PN.RND, P.+, PN.+, P.-, PN.-. P.+W, PN.+W, P.-W, PN.-W
+- **NEW**: new Telex ops: TO.CV.CALIB, TO.ENV
+- **NEW**: new Kria ops: KR.CV, KR.MUTE, KR.TMUTE, KR.CLK, ME.CV
+- **NEW**: new aliases: $, RND, RRND, WRP, SCL
+- **NEW**: telex, ansible, just friends, w/ added to the help screen
+- **FIX**: i2c initialization delayed to account for ER-301 bootup
+- **FIX**: last screen saved to flash
+- **FIX**: knob jitter when loading/saving scenes reduced
+- **FIX**: [duplicate commands not added to history](https://github.com/monome/teletype/issues/99)
+- **FIX**: `SCALE` precision improved
+- **FIX**: `PARAM` set properly when used in the init script
+- **FIX**: `PARAM` and `IN` won't reset to 0 after `INIT.DATA`
+- **FIX**: [`PN.HERE`, `P.POP`, `PN.POP` will update the tracker screen](https://github.com/monome/teletype/issues/151)
+- **FIX**: [`P.RM` was 1-based, now 0-based](https://github.com/monome/teletype/issues/149)
+- **FIX**: [`P.RM` / `PN.RM` will not change pattern length if deleting outside of length range](https://github.com/monome/teletype/issues/150)
+- **FIX**: [`JI` op fixed](https://llllllll.co/t/teletype-the-ji-op/10553)
+- **FIX**: [`TIME` and `LAST` are now 1ms accurate](https://github.com/monome/teletype/issues/144)
+- **FIX**: [`RAND` / `RRAND` will properly work with large range values](https://github.com/monome/teletype/issues/143)
+- **FIX**: [`L .. 32767` won't freeze](https://github.com/monome/teletype/issues/148)
 - **FIX**: I now accessible to child SCRIPTS
-- **NEW**: new ops for Ansible: KR.CV, KR.MUTE, KR.TMUTE, KR.CLK, ME.CV
-- **NEW**: new ops for W/: WS.PLAY, WS.REC, WS.LOOP, WS.CUE
 
 ## v2.2
 - **NEW**: added a cheat sheet PDF

docs/advanced.md

@@ -73,7 +73,7 @@ IF X: CV 1 N 60; TR.P 1
 IF Y: TR.P 1; TR.P 2; TR.P 3
 ```
 
-Sub commands can also be used with `L`, though due to (current) limitations on how many separate numbers, `OP`s and `MOD`s are allowed in a single command this can be tricky (even if you can fit the text on a line).
+Sub commands can also be used with `L`.
 
 ## Aliases
 
@@ -110,7 +110,7 @@ Aliases are entirely optional, most `OP`s do not have aliases. Consult the `OP`
 
 ## Avoiding non-determinism
 
-Although happy accidents in the modular world are one of it's many joys, when writing computer programs they can be incredibly frustrating. Here are some small tips to help keep things predictable (when you want to them to be):
+Although happy accidents in the modular world are one of it's many joys, when writing computer programs they can be incredibly frustrating. Here are some small tips to help keep things predictable (when you want them to be):
 
   1. **Don't use variables unless you need to.**
 
@@ -127,3 +127,51 @@ Although happy accidents in the modular world are one of it's many joys, when wr
   4. **Avoid using `A`, `B`, `C` and `D` to refer to the trigger outputs, instead use the numerical values directly.**
 
      As `A-D` are variables, they may no longer contain the values `1-4`, and while this was the recommend way to name triggers, it is no longer consider ideal. Newer versions of the Teletype hardware have replaced the labels on the trigger outputs, with the numbers `1` to `4`.
+
+## Grid integration
+
+Grid integration can be described very simply: it allows you to use grid with
+teletype. However, there is more to it than just that. You can create custom
+grid interfaces that can be tailored individually for each scene. Since it's
+done with scripts you can dynamically change these interfaces at any point -
+you could even create a dynamic interface that reacts to the scene itself or
+incoming triggers or control voltages.
+
+You can simply use grid as an LED display to visualize your scene. Or make it
+into an earthsea style keyboard. You can create sequencers, or control surfaces
+to control other sequencers. The grid operators simplify building very complex
+interfaces, while something simple like a bank of faders can be done with just
+two lines of scripts.
+
+Grid integration consists of 3 main features: grid operators, Grid Visualizer,
+and Grid Control mode. Grid operators allow you to draw on grid or create grid
+controls, such as buttons and faders, that can trigger scripts when pressed. 
+As with any other operators you can execute them in Live screen or use them in
+any of your scripts.
+
+Grid Visualizer provides a virtual grid within the Teletype itself:
+
+![Grid Visualizer](img/gridvisualizer.jpg)
+
+It can be very useful while developing a script as you don't have to switch
+between the grid and the keyboard as often. To turn it on navigate to Live
+screen and press `Alt-G` (press again to switch to Full View / turn it off).
+You can also emulate button presses, which means it can even be used as an 
+alternative to grid if you don't have one, especially in full mode - try it
+with one of the many [grid scenes](https://github.com/scanner-darkly/teletype/wiki/CODE-EXCHANGE)
+already developed. For more information on how to use it please refer to 
+[the Grid Visualizer documentation](https://github.com/scanner-darkly/teletype/wiki/GRID-VISUALIZER).
+
+Grid Control Mode is a built in grid interface that allows you to use grid to
+trigger and mute scripts, edit variables and tracker values, save and load
+scenes, and more. It's available in addition to whatever grid interface you
+develop - simply press the front panel button while the grid is attached. It can
+serve as a simple way to use grid to control any scene even without using grid
+ops, but it can also be very helpful when used together with a scripted grid
+interface. For more information and diagrams please refer to 
+[the Grid Control documentation](https://github.com/scanner-darkly/teletype/wiki/GRID-CONTROL-MODE),
+
+If you do want to try and build your own grid interfaces 
+[the Grid Studies](https://github.com/scanner-darkly/teletype/wiki/GRID-INTEGRATION)
+is the best place to start.
+

docs/intro.md

@@ -3,8 +3,7 @@
 Teletype is a dynamic, musical event triggering platform.
 
 * [Teletype Studies](https://monome.org/docs/modular/teletype/studies-1) - guided series of tutorials
-* [PDF command reference chart](https://monome.org/docs/modular/teletype/TT_commands_2.1.pdf)
-— [PDF key reference chart](https://monome.org/docs/modular/teletype/TT_keys_card_1.3.pdf)
+* [PDF command reference chart](https://monome.org/docs/modular/teletype/TT_commands_3.0.pdf)
 — [PDF scene recall sheet](https://monome.org/docs/modular/teletype/TT_scene_RECALL_sheet.pdf)
 — [Default scenes](http://monome.org/docs/modular/teletype/scenes-1.0/)
 

docs/keys.md

@@ -10,7 +10,7 @@ These bindings work everywhere.
 | `<esc>`                      | preset read mode, or return to last mode       |
 | `alt-<esc>`                  | preset write mode                              |
 | `win-<esc>`                  | clear delays, stack and slews                  |
-| `shift-alt-?`                | help text, or return to last mode              |
+| `shift-alt-?` / `alt-h`      | help text, or return to last mode              |
 | `<F1>` to `<F8>`             | run corresponding script                       |
 | `<F9>`                       | run metro script                               |
 | `<F10>`                      | run init script                                |
@@ -33,6 +33,8 @@ In most cases, the clipboard is shared between _live_, _edit_ and the 2 _preset_
 |--------------------------------|-----------------------------------------|
 | `<left>` / `ctrl-b`            | move cursor left                        |
 | `<right>` / `ctrl-f`           | move cursor right                       |
+| `ctrl-<left>`                  | move left by one word                   |
+| `ctrl-<right>`                 | move right by one word                  |
 | `<home>` / `ctrl-a`            | move to beginning of line               |
 | `<end>` / `ctrl-e`             | move to end of line                     |
 | `<backspace>` / `ctrl-h`       | backwards delete one character          |
@@ -46,16 +48,27 @@ In most cases, the clipboard is shared between _live_, _edit_ and the 2 _preset_
 
 ## Live mode
 
-| Key              | Action              |
-|------------------|---------------------|
-| `<down>` / `C-n` | history next        |
-| `<up>` / `C-p`   | history previous    |
-| `<enter>`        | execute command     |
-| `~`              | toggle variables    |
-| `[` / `]`        | switch to edit mode |
+| Key                  | Action                   |
+|----------------------|--------------------------|
+| `<down>` / `C-n`     | history next             |
+| `<up>` / `C-p`       | history previous         |
+| `<enter>`            | execute command          |
+| `~`                  | toggle variables         |
+| `[` / `]`            | switch to edit mode      |
+| `alt-g`              | toggle grid visualizer   |
+| `alt-<arrows>`       | move grid cursor         |
+| `alt-shift-<arrows>` | select grid area         |
+| `alt-<space>`        | emulate grid press       |
+| `alt-/`              | switch grid pages        |
+| `alt-\`              | toggle grid control view |
+| `alt-<prt sc>`       | insert grid x/y/w/h      |
+
+In full grid visualizer mode pressing `alt` is not required.
 
 ## Edit mode
 
+In _edit_ mode multiple lines can be selected and used with the clipboard.
+
 | Key                | Action                    |
 |--------------------|---------------------------|
 | `<down>` / `C-n`   | line down                 |
@@ -65,6 +78,12 @@ In most cases, the clipboard is shared between _live_, _edit_ and the 2 _preset_
 | `<enter>`          | enter command             |
 | `shift-<enter>`    | insert command            |
 | `alt-/`            | toggle line comment       |
+| `shift-<up>`       | expand selection up       |
+| `shift-<down>`     | expand selection down     |
+| `alt-<delete>`     | delete selection          |
+| `alt-<up>`         | move selection up         |
+| `alt-<down>`       | move selection down       |
+| `ctrl-z`           | undo (3 levels)           |
 
 ## Tracker mode
 
@@ -100,6 +119,8 @@ The tracker mode clipboard is independent of text and code clipboard.
 | `<space>`           | toggle non-zero to zero, and zero to 1                                                |
 | `0` to `9`          | numeric entry                                                                         |
 | `shift-2` (`@`)     | toggle turtle display marker (`<`)                                                    |
+| `ctrl-alt`          | insert knob value scaled to 0..31                                                     |
+| `ctrl-shift`        | insert knob value scaled to 0..1023                                                   |
 
 ## Preset read mode
 

docs/ops/controlflow.toml

@@ -159,6 +159,7 @@ short = "potentially execute command with probability `x` (0-100)"
 [SCRIPT]
 prototype = "SCRIPT"
 prototype_set = "SCRIPT x"
+aliases = ["$"]
 short = "get current script number, or execute script `x` (1-8), recursion allowed"
 description = """
 Execute script `x` (1-8), recursion allowed.
@@ -209,7 +210,8 @@ prototype = "INIT.DATA"
 short = "clears all data held in all variables"
 description = """
 
-Clears the following variables and resets them to default values: A, B, C, D, CV slew, Drunk min/max, M, O, Q, R, T, TR, CV input, and the Paramter knob
+Clears the following variables and resets them to default values: A, B, C, D, CV slew, Drunk min/max, M, O, Q, R, T, TR. 
+Does not affect the CV input (IN) or the Parameter knob (PARAM) values.
 """
 
 ["INIT.P"]

docs/ops/er301.md

@@ -0,0 +1,3 @@
+## Orthogonal Devices ER-301 Sound Computer
+
+The ER-301 is a voltage-controllable canvas for digital signal processing algorithms available from Orthogonal Devices. It can communicate with the Teletype to send up to 100 triggers and 100 CV values per device. Up to three devices are software-selectable and correlate to outputs up to 300.

docs/ops/er301.toml

@@ -0,0 +1,36 @@
+["SC.TR"]
+prototype = "SC.TR x y"
+short = "Set trigger output for the ER-301 virtual output x to y (0-1)"
+
+["SC.TR.POL"]
+prototype = "SC.TR.POL x y"
+short = "Set polarity of trigger for the ER-301 virtual output x to y (0-1)"
+
+["SC.TR.TIME"]
+prototype = "SC.TR.TIME x y"
+short = "Set the pulse time for the ER-301 virtual trigger `x` to `y` in ms"
+
+["SC.TR.TOG"]
+prototype = "SC.TR.TOG x"
+short = "Flip the state for the ER-301 virtual trigger output `x`"
+
+["SC.TR.PULSE"]
+prototype = "SC.TR.PULSE x"
+aliases = ["SC.TR.P"]
+short = "Pulse the ER-301 virtual trigger output `x`"
+
+["SC.CV"]
+prototype = "SC.CV x y"
+short = "CV target value for the ER-301 virtual output `x` to value `y`"
+
+["SC.CV.OFF"]
+prototype = "SC.CV.OFF x y"
+short = "CV offset added to the ER-301 virtual output `x`"
+
+["SC.CV.SET"]
+prototype = "SC.CV.SET x"
+short = "Set CV value for the ER-301 virtual output `x`"
+
+["SC.CV.SLEW"]
+prototype = "SC.CV.SLEW x y"
+short = "Set the CV slew time for the ER-301 virtual output `x` in ms"

docs/ops/fader.md

@@ -0,0 +1,3 @@
+## 16n Faderbank
+
+The 16n Faderbank is an open-source controller that can be polled by the Teletype to read the positions of its 16 sliders.

docs/ops/fader.toml

@@ -0,0 +1,4 @@
+["FADER"]
+prototype = "FADER x"
+aliases = ["FB"]
+short = "reads the value of the `FADER` slider `x`; default return range is from 0 to 16383"

docs/ops/grid.md

@@ -0,0 +1,38 @@
+## Grid
+Grid operators allow creating scenes that can interact with grid connected to
+teletype (important: grid must be powered externally, do not connect it directly
+to teletype!). You can light up individual LEDs, draw shapes and create controls
+(such as buttons and faders) that can be used to trigger and control scripts.
+You can take advantage of grid operators even without an actual grid by using
+the built in Grid Visualizer.
+
+For more information on grid integration see Advanced section and 
+[Grid Studies](https://github.com/scanner-darkly/teletype/wiki/GRID-INTEGRATION).
+
+As there are many operators let's review some naming conventions that apply to
+the majority of them. All grid ops start with `G.`. For control related ops this
+is followed by 3 letters specifying the control: `G.BTN` for buttons, `G.FDR`
+for faders. To define a control you use the main ops `G.BTN` and `G.FDR`. To
+define multiple controls replace the last letter with `X`: `G.BTX`, `G.FDX`. 
+
+All ops that initialize controls use the same list of parameters: id,
+coordinates, width, height, type, level, script. When creating multiple controls
+there are two extra parameters: the number of columns and the number of rows.
+Controls are created in the current group (set with `G.GRP`). To specify a
+different group use the group versions of the 4 above ops - `G.GBT`, `G.GFD`,
+`G.GBX`, `G.GFX` and specify the desired group as the first parameter.
+
+All controls share some common properties, referenced by adding a `.` and:
+
+* `EN`: `G.BTN.EN`, `G.FDR.EN` - enables or disables a control
+* `V`: `G.BTN.V`, `G.FDR.V` - value, 1/0 for buttons, range value for faders
+* `L`: `G.BTN.L`, `G.FDR.L` - level (brightness level for buttons and coarse faders, max value level for fine faders)
+* `X`: `G.BTN.X`, `G.FDR.X` - the X coordinate
+* `Y`: `G.BTN.Y`, `G.FDR.Y` - the Y coordinate
+
+To get/set properties for individual controls you normally specify the control
+id as the first parameter: `G.FDR.V 5` will return the value of fader 5. Quite
+often the actual id is not important, you just want to work with the latest
+control pressed. As these are likely the ops to be used most often they are
+offered as shortcuts without a `.`: `G.BTNV` returns the value of the last
+button pressed, `G.FDRL 4` will set the level of the last fader pressed etc etc.