Merge pull request #75 from samdoshi/docs

Teletype firmware 2.0

.gitignore

@@ -41,9 +41,14 @@
 # Debug files
 *.dSYM/
 
+# Python
+__pycache__/
+
 # Build outputs
 /src/match_token.c
 /src/scanner.c
 /simulator/tt
 /module/gitversion.c
 /tests/tests
+/docs/teletype.pdf
+/docs/teletype.html

CHANGELOG.md

@@ -1,25 +1,30 @@
 # Changelog
 
-## vNext
+## v2.0
 - **BREAKING**: remove `II` op. Ops that required it will now work with out it. (e.g. `II MP.PRESET 1` will become just `MP.PRESET 1`)
 - **BREAKING**: merge the `MUTE` and `UNMUTE` ops. Now `MUTE x` will return the mute status for trigger `x` (`0` is unmuted, `1` is muted), and `MUTE x y` will set the mute for trigger `x` (`y = 0` to unmute, `y = 1` to mute)
+- **BREAKING**: remove unused Meadowphysics ops: `MP.SYNC`, `MP.MUTE`, `MP.UNMUTE`, `MP.FREEZE`, `MP.UNFREEZE`
+- **BREAKING**: rename Ansible Meadowphysics ops to start with `ME`
 - **NEW**: sub commands, use a `;` separator to run multiple commands on a single line, e.g. `X 1; Y 2`
-- **NEW**: key bindings rewritten, see [docs](./docs/modes.md)
-- **NEW**: multiple commands on each line separated by ':'
+- **NEW**: key bindings rewritten
 - **NEW**: aliases: `+` for `ADD`, `-` for `SUB`, `*` for `MUL`, `/` for `DIV`, `%` for `MOD`, `<<` for `LSH`, `>>` for `RSH`, `==` for `EQ`, `!=` for `NE`, `<` for `LT`, `>` for `GT`, `<=` for `LTE`, `>=` for `GTE`, `!` for `EZ`, `&&` for `AND`, `||` for `OR`, `PRM` for `PARAM`, `TR.P` for `TR.PULSE`
 - **NEW**: new ops: `LTE` (less than or equal), and `GTE` (greater than or equal)
 - **NEW**: new pattern ops: `PN.L`, `PN.WRAP`, `PN.START`, `PN.END`, `PN.I`, `PN.HERE`, `PN.NEXT`, `PN.PREV`, `PN.INS`, `PN.RM`, `PN.PUSH` and `PN.POP`
 - **NEW**: USB disk loading and saving works at any time
+- **NEW**: `M` limited to setting the metronome speed to 25ms, added `M!` to allow setting the metronome at unsupported speeds as low as 2ms
+- **NEW**: TELEX Aliases: `TO.TR.P` for `TO.TR.PULSE` (plus all sub-commands) and `TI.PRM` for `TI.PARAM` (plus all sub-commands)
+- **NEW**: TELEX initialization commands: `TO.TR.INIT n`, `TO.CV.INIT n`, `TO.INIT x`, `TI.PARAM.INIT n`, `TI.IN.INIT n`, and `TI.INIT x`
 - **IMP**: new Ragel parser backend
 - **IMP**: script recursion enhanced, maximum recursion depth is 8, and self recursion is allowed
 - **IMP**: removed the need to prefix `:` and `;` with a space, e.g. `IF X : TR.PULSE 1` becomes `IF X: TR.PULSE`
+- **IMP**: `AND` and `OR` now work as boolean logic, rather than bitwise, `XOR` is an alias for `NE`
 - **FIX**: divide by zero errors now explicitly return a 0 (e.g. `DIV 5 0` now returns 0 instead of -1), previously the behaviour was undefined and would crash the simulator
 - **FIX**: numerous crashing bugs with text entry
 - **FIX**: `i2c` bus crashes under high `M` times with external triggers
-- **NEW**: TELEX Aliases: `TO.TR.P` for `TO.TR.PULSE` (plus all sub-commands) and `TI.PRM` for `TI.PARAM` (plus all sub-commands)
-- **NEW**: TELEX initialization commands: `TO.TR.INIT n`, `TO.CV.INIT n`, `TO.INIT x`, `TI.PARAM.INIT n`, `TI.IN.INIT n`, and `TI.INIT x`
+- **FIX**: `P.I` and `PN.I` no longer set values longer than allowed
+- **FIX**: `VV` works correctly with negative values
 
-## v1.41
+## v1.4.1
 - **NEW**: added Ansible remote commands `LV.CV` and `CY.CV`
 - **NEW**: Added TELEX Modules Support for the TXi and the TXo
 - **NEW**: 75 New Operators Across the Two Modules
@@ -29,7 +34,7 @@
 - **NEW**: Experimental output operators add oscillators, envelopes, independent metronomes, pulse dividing, etc.
 - **NEW**: [Full List of Methods Found and Maintained Here](https://github.com/bpcmusic/telex/blob/master/commands.md)
 
-## v1.21
+## v1.2.1
 - **NEW**: Just Friends ops: `JF.GOD`, `JF.MODE`, `JF.NOTE`, `JF.RMODE`, `JF.RUN`, `JF.SHIFT`, `JF.TICK`, `JF.TR`, `JF.TUNE`, `JF.VOX`, `JF.VTR`
 
 ## v1.2

Makefile

@@ -1,3 +1,33 @@
-.PHONY: format
+.PHONY: release format \
+	clean clean-docs clean-module clean-simulator clean-tests clean-zip
+
+release: teletype.zip
+
+clean: clean-docs clean-module clean-simulator clean-tests
+
+clean-docs:
+	cd docs && make clean && cd ..
+
+clean-module:
+	cd module && make clean && cd ..
+
+clean-simulator:
+	cd simulator && make clean && cd ..
+
+clean-tests:
+	cd tests && make clean && cd ..
+
+clean-zip:
+	rm -f teletype.zip
+
+teletype.zip: clean-zip
+	cd module && make && cd .. && \
+	cd docs && make teletype.pdf && cd .. && \
+	zip -j teletype.zip \
+		module/teletype.hex \
+		module/flash.sh \
+		module/update_firmware.command \
+		docs/teletype.pdf
+
 format:
 	find . -type f -name "*.c" -o -name "*.h" | xargs clang-format -style=file -i

README.md

@@ -12,6 +12,7 @@ http://monome.org/docs/modular/teletype
 - `module`: `main.c` and additional code for the Eurorack module (e.g. IO and UI)
 - `tests`: algorithm tests
 - `simulator`: a (very) simple teletype command parser and simulator
+- `docs`: files used to generate the teletype manual
 
 ## Building
 
@@ -66,3 +67,46 @@ To format the code using `clang-format`, run `make format` in the project's root
 
 [libavr32]: https://github.com/monome/libavr32
 [ragel]: http://www.colm.net/open-source/ragel/
+
+## Documentation
+
+In order to build the documentation you will need Python 3.6 or greater, [Pandoc][], as well as the Python libraries specified in the [`requirements.pip`][requirements.pip] file. In addition, to generate the PDF output you will also require [TexLive][] (or [MacTex][]).
+
+On OSX the dependencies can be installed with `brew`.
+
+```bash
+brew install python3
+brew install pandoc
+brew cask install mactex  # warning, MacTex is a very large install!
+cd utils
+pip3 install -r requirements.pip
+```
+
+On Linux I would suggest using [`virtualenv`][virtualenv] to install all the Python dependencies (including those in the [`requirements.pip`][requirements.pip] file), and to ensure that the `python3` binary is version 3.6 or greater instead of the default of your distro.
+
+[virtualenv]: https://virtualenv.pypa.io/en/stable/
+
+To generate the documentation:
+
+```bash
+cd docs
+make               # build both teletype.pdf and teletype.html
+make teletype.pdf  # build just teletype.pdf (requires TexLive or MacTex)
+make teletype.html # build just teletype.html
+```
+
+[requirements.pip]: utils/requirements.pip
+[Pandoc]: http://pandoc.org/
+[TexLive]: https://www.tug.org/texlive/
+[MacTex]: https://www.tug.org/mactex/
+
+## Making a Release
+
+To create a `teletype.zip` file containing:
+
+ - `teletype.hex`
+ - `flash.sh`
+ - `update_firmware.command`
+ - `teletype.pdf`
+
+Run `make release` in the project's root directory

docs/Makefile

@@ -0,0 +1,14 @@
+.PHONY: build clean
+
+build: teletype.pdf teletype.html
+
+clean:
+	rm -f teletype.pdf && rm -f teletype.html
+
+teletype.pdf: $(wildcard *.md ops/*.md ops/*.toml) \
+		../utils/docs.py ../CHANGELOG.md
+	../utils/docs.py teletype.pdf
+
+teletype.html: $(wildcard *.md ops/*.md ops/*.toml) \
+		../utils/docs.py ../CHANGELOG.md
+	../utils/docs.py teletype.html

docs/advanced.md

@@ -0,0 +1,129 @@
+# Advanced
+
+## Teletype terminology
+
+Here is a picture to help understand the naming of the various parts of a Teletype command:
+
+![Teletype command terminology](img/terminology.jpg)
+
+`COMMAND`
+
+: The entire command, e.g. `IF X: Y 1; Z 2;`.
+
+`PRE`
+
+: The (optional)  part before the _`PRE SEP`_, e.g. `IF X`.
+
+`POST`
+
+: The part after the _PRE SEP_, e.g. `Y 1; Z 2`.
+
+`SUB`
+
+: A sub command (only allowed in the _`POST`_), e.g. `Y 1`, or `Z 2`.
+
+`PRE SEP`
+
+: A _colon_, only one is allowed.
+
+`SUB SEP`
+
+: A _semi-colon_, that separates sub commands (if used), only allowed in the _`POST`_.
+
+`NUM`
+
+: A number between `−32768` and `32767`.
+
+`OP`
+
+: An _operator_, e.g. `X`, `TR.PULSE`
+
+`MOD`
+
+: A _modifier_, e.g. `IF`, or `L`.
+
+## Sub commands
+
+Sub commands allow you to run multiple commands on a single line by utilising a semi-colon to separate each command, for example the following script:
+
+```
+X 0
+Y 1
+Z 2
+```
+
+Can be rewritten using sub commands as:
+
+```
+X 0; Y 1; Z 2
+```
+
+On their own sub commands allow for an increased command density on the Teletype. However when combined with `PRE` statements, certain operations become a lot easier.
+
+Firstly, sub commands cannot be used before a `MOD` or in the `PRE` itself. For example, the following is **not allowed**:
+
+```
+X 1; IF X: TR.PULSE 1
+```
+
+We can use them in the `POST` though, particularly with an `IF`, for example:
+
+```
+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).
+
+## Aliases
+
+In general, aliases are a simple concept to understand. Certain `OP`s have been given shorted names to save space and the amount of typing, for example:
+
+```
+TR.PULSE 1
+```
+
+Can be replaced with:
+
+```
+TR.P 1
+```
+
+Where confusion may arise is with the symbolic aliases that have been given to some of the maths `OP`s. For instance `+` is given as an alias for `ADD` and it _must_ be used as a direct replacement:
+
+```
+X ADD 1 1
+X + 1 1
+```
+
+The key to understanding this is that the Teletype uses _prefix notation_[^polish] always, even when using mathematical symbols.
+
+[^polish]: Also know as _Polish notation_.
+
+The following example (using _infix notation_) **will not work**:
+
+```
+X 1 + 1
+```
+
+Aliases are entirely optional, most `OP`s do not have aliases. Consult the `OP` tables and documentation to find them.
+
+## 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):
+
+  1. **Don't use variables unless you need to.**
+
+     This is not to say that variables are not useful, rather it's the opposite and they are extremely powerful. But it can be hard to keep a track of what each variable is used for and on which script it is used. Rather, try to save using variables for when you do want non-deterministic (i.e. _variable_) behaviour.
+
+  2. **Consider using `I` as a temporary variable.**
+
+     If you do find yourself needing a variable, particularly one that is used to continue a calculation on another line, consider using the variable `I`. Unlike the other variables, `I` is overwritten whenever `L` is used, and as such, is implicitly transient in nature. One should never need to worry about modifying the value of `I` and causing another script to malfunction, as no script should ever assume the value of `I`.
+
+  3. **Use `PN` versions of `OP`s.**
+
+     Most `P` `OP`s are now available as `PN` versions that ignore the value of `P.I`. (e.g. `PN.START` for `P.START`). Unless you explicitly require the non-determinism of `P` versions, stick to the `PN` versions (space allowing).
+
+  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`.

docs/modes.md

@@ -1,3 +1,4 @@
+# Modes
 
 ## Global key bindings
 
@@ -9,14 +10,16 @@ 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                  |
-| `<print screen>`             | help text, or return to last mode              |
+| `<alt>-?`                    | help text, or return to last mode              |
 | `<F1>` to `<F8>`             | run corresponding script                       |
 | `<F9>`                       | run metro script                               |
 | `<F10>`                      | run init script                                |
 | `alt-<F1>` to `alt-<F8>`     | edit corresponding script                      |
 | `alt-<F9>`                   | edit metro script                              |
 | `alt-<F10>`                  | edit init script                               |
 | `<numpad-1>` to `<numpad-8>` | run corresponding script                       |
+| `<num lock>` / `<F11>`       | jump to pattern mode                           |
+| `<print screen>` / `<F12>`   | jump to live mode                              |
 
 ## Text editing
 

docs/ops.md

@@ -0,0 +1,2 @@
+# OPs and MODs
+

docs/ops/ansible.md

@@ -0,0 +1,2 @@
+## Ansible
+