1
0
Fork 0
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
baconscript/README.md

131 lines
4.1 KiB

4 years ago
# Bacon Script
A theoretical exercise to control a Hog 4 via OSC, with comment macros.
4 years ago
The comment macro grammar described in `CommentMacro.g4` is based upon the Hog 3.9 manual, Chapter 22.4. The python3 implementation in `OscCommentMacroListener.py` is based on Chapter 24.2 in the same manual.
4 years ago
Some macros are unsupported/unsupportable with this method. Some macro features, like timing, are not yet implemented. Refer to the **Features** table for specific notes.
4 years ago
## Installing
Install Antlr4 for input and Python-OSC for output.
```bash
$ pip3 install antlr4-python3-runtime python-osc
4 years ago
```
Use git to retrieve a copy of the code.
```bash
$ git clone http://company235.com/git/kevin/baconscript.git
$ cd baconscript
```
4 years ago
## Testing
4 years ago
4 years ago
Edit `server.cfg` to the correct values for your Hog4.
`comment.py` will accept macros on the command line, or will run an interactive prompt. Use the builtin command `exit` to quit the interactive prompt.
```bash
4 years ago
$ ./comment.py
Adding Hog device at net# 1
comment# GL1
Go on List 1
comment# exit
```
Run a baconscript file by passing the script file to `comment.py` as standard input.
```bash
$ ./comment.py < example.bs
4 years ago
```
4 years ago
4 years ago
## Developing
4 years ago
4 years ago
You must also install the ANTLR tool. On a mac with homebrew, do:
```bash
4 years ago
$ brew install antlr
```
4 years ago
4 years ago
Update the lexer and parser for Python3
```bash
4 years ago
$ antlr -Dlanguage=Python3 CommentMacro.g4
```
## Features
Only features that are supported in both OSC and Comment Macros are able to be
implemented in baconscript. This table lists all comment macros (as of 3.9)
2 years ago
that are implemented in python.
4 years ago
| Grammar Feature | eg. | Supported |
| ----------------|-----|-----------|
| fade times | t5 | no |
| multiple targets | 1,2 | Yes |
| ranges | 1>4 | Yes, intervals of 1 |
4 years ago
| multiple macros | GM1:GL3 | Yes |
| network devices | h4 | Yes, H devices only |
| wait times | WAIT1 | BaconScript only; Continue script after n seconds.
Benefiting from the LL(*) parser provided by ANTLR, `multiple targets` and
`ranges` may be combined ad infinitum. This is a known deviation from the
Comment Macro syntax.
4 years ago
2 years ago
### Standard Macros
4 years ago
| Macro | Function | Supported | Notes |
|-------|----------|-----------|-------|
2 years ago
| GM | Go Master | Yes | GOTO on current master only |
4 years ago
| HM | Halt Master | Yes | |
| AM | Assert Master | Partial | on current master only |
| RM | Release Master | Partial | on current master only |
| RA | Release All | Yes | |
4 years ago
| RO | Release Others | no | |
| FM | Fade Master | Partial | no times, no * |
| FGM | Fade Grand Master | Partial | no times |
4 years ago
| CM | Choose Master | Yes | |
| GL | Go List | Yes | |
| HL | Halt List | Yes | |
| AL | Assert List | no | |
| RL | Release List | Yes | |
| GB | Go Batch | no | |
| HB | Halt Batch | no | |
| AB | Assert Batch | no | |
| RB | Release Batch | no | |
| GS | Go Scene | Yes | |
| HS | Halt Scene | Yes | |
| AS | Assert Scene | no | |
| RS | Release Scene | Yes | |
| CP | Change Page | Partial | only CP+ and CP- |
4 years ago
| RV | Recall View | no | |
| ET | Enable Timecode | no | |
| DT | Disable Timecode | no | |
| OT | Open Timecode Toolbar | no | |
| MS | Midi String | no | possible? |
| MN | Midi Note | no | |
| RN | Reset Node | no | |
| GK | Go Keystroke Macro | Yes | |
| HK | Pause Keystroke Macro | Yes | |
| RK | Stop Keystroke Macro | Yes | . |
4 years ago
2 years ago
### Additional Macros
BaconScript also supports several macros that aren't present on Hog4, but become possible/desirable when wrapping OSC.
| Macro | Function | Notes |
|-------|----------|-------|
| INT | Select an Intensity Pallet | keypress macro |
| POS | Select a Position Pallet | keypress macro |
| COLR | Select a Colour Pallet | keypress macro |
| BEAM | Select a Beam Pallet | keypress macro |
| WAIT | Pause for n seconds | |
| PASS | Null instruction | |
4 years ago
## Future Work
Pleas feel welcome to submit pull requests or patches that enable support for:
* Sending target ranges as OSC arguments
2 years ago
* Hog4 does not support multiple arguments to a single path.
4 years ago
* Send multi-macro line as an OSC batch
* HogOS 3.9 has a bug involving batches. Whereby only every-other member of the batch will be interpreted.
4 years ago
* Timing on master fades