Dull Programming Guide - mrstefangrimm/Parc GitHub Wiki

This manual gives brief introduction to the Dull programming language. Dull is a new invention and this is currently all information there is.

Dull is the programming language is used to program a Parc remote control. Dull is very limited an maybe it should not even be called programming language. It is called "dull" because it is very simple, simplistic, limited.

What can you do with Dull:

• Define a sequence of keyboard key presses or Bluetooth commands
• Define a PIN

What you cannot do:

• Define data structures, functions, loops and may things more.

A program is a sequence of program steps. A program starts and ends with curly braces ({ ... }). The opening brace is followed by the mode and the function key the program is for. The program steps are delimited by semicolons.

Example of a program that writes Hello World on two lines when button A is pressed: { 0 A: UT Hello; UK <Enter>; UT World; }

Delay the next command for a given number of milliseconds.

Example: W 1000;

A single key stroke is sent with UK (USB Keycode) and BK (Bluetooth Keycode) command. The keycodes are found on the internet:

• Arduino Keyboard library Keyboard.h
• Adafruit HID Keyboard Codes

The Arduino keyboard library is used to send keycodes over USB. Therefore the Arduino library is the reference. For Bluetooth, the Adafruit documentation is the reference.

Examples:

• UK 'A';
• UK 0x41;
• BK <Shift> 0x4;

'A' is the same as 0x41, which is 65 in the ASCII table.

USB and BLE do not have the same keycodes

The most common keycodes have a predefined token in Dull. Instead of UK 0xB3 or BK 0x2B for sending an Tab-character, UK <Tab> resp. BK <Tab> can be used.

Predefined tokens are: <Del>, <Tab>, <Enter>, <Space>

Examples:

• BK <Enter>;
• UK <Space>;

A typical modifier is <Shift> to send a capital letter. Modifiers are: <Ctrl>, <Shift>, <Alt>, <Win>

Examples:

• UK <Win> 'l';
• BK <Ctrl> <Alt> <Del>;

To repeat the same keypress, use the -r option or modifier.

Examples:

• BK -r12 <Tab>;

This is only available for USB. The example below formats a document in Visual Studio.

Example:

• UK <Ctrl> "k d";

The text command sends a array of characters. Quote the text if the text contains a space.

Examples:

• UT hello;
• BT "hello world";

A Ble control key is text command that is sent to the receiving device (e.g. a Smartphone or your PC) and is interpreted there. If the receiving device or program does not know the command, nothing is executed. BC HOME for example presses the Home button on a Smartphone but is ignored on the PC.

Two internet sources are helpful:

• Adafruit BLEHIDCONTROLKEY
• Free BSD USB HID Usage

Examples:

• BC Volume+;
• BC 0xE9;

Volume+ is the same as 0xE9. The term "Volume+" is from the Adafruit website and "0xE9" from the Free BSD website.

To set the personal identification number (PIN). The PIN is unique for the device and the syntax is different to the command syntax. The PIN is a 4-bit value and it is possible to set the number retries (0 - 3).

Example with two retries): { P N: 1 0 1 0 2}

The help lists all the 20 available program slots and if they are in use or not.

Example: ?

I tried to follow as described on Wikipedia. Example: <opt-whitespace> ::= " " <opt-whitespace> | ""

<Program> ::= '{' <Address> : <Commands> '}'
<Address> ::= <Mode> ' ' <Button>
<Mode> ::= 0 | 1 | 2 | 3 
<Button> ::= A | B | C | D | E
<Commands> ::= '' | ';' | <Command> ';' | <Command> ';' <Commands> ';'
<Command> ::= <WaitCmd> | <UsbKeycodeCmd> | <UsbTextCmd> | <BleKeycodeCmd> | <BleTextCmd> | <BleControlkeyCmd>
<WaitCmd> ::= W ' ' <Duration>
<UsbKeycodeCmd> ::= <UsbKeycodeCmdSingle> | <UsbKeycodeCmdRepeated> | <UsbKeycodeCmdTwoKeysAtOnce>
<UsbKeycodeCmdSingle> ::= UK ' ' <Modifiers> ' ' <UsbKeycode> | UK ' ' <Modifier> | UK ' ' <UsbKeycode>
<UsbKeycodeCmdRepeated> ::= UK ' ' -r <Digit> ' ' <Modifiers> ' ' <UsbKeycode> ' ' | UK ' ' -r <Digit> ' '<Modifiers> | UK ' ' -r <Digit> ' '<UsbKeycode>
<UsbKeycodeCmdTwoKeysAtOnce> ::= UK ' ' <Modifiers> ' ' '"' <UsbKeycode> ' ' <Char> '"'
<UsbTextCmd> ::= UT ' ' <Text>
<BleKeycodeCmd> ::= <BleKeycodeCmdSingle> | <BleKeycodeCmdRepeated>
<BleKeycodeCmdSingle> ::= BK ' ' <Modifiers> ' ' <BleKeycode> | BK ' ' <Modifier> | BK ' ' <BleKeycode>
<BleKeycodeCmdRepeated> ::= BK ' ' -r <Digit> ' ' <Modifiers> ' ' <BleKeycode> | BK ' ' -r ' ' <Digit> ' ' <Modifiers> | BK ' ' -r <Digit> ' ' <BleKeycode>
<BleTextCmd> ::= BT ' ' <Text>
<BleControlkeyCmd> ::= <Hex8> | <Hex8> ' ' <Duation> | <Chars> | <Chars> ' ' <Duration>
<Modifiers> ::= <Modifier> | <<Modifier> > ' ' <Modifiers>
<Modifier> ::= '<Ctrl>' | '<Shift>' | '<Alt>' | '<Win>'
<UsbKeycode> ::= '<Enter>' | '<Del>' | '<Space>' | <Tab> | <8-bit-Number> | ''' <Char> '''
<BleKeycode> ::= '<Enter>' | '<Del>' | '<Space>' | <Tab> | <8-bit-Number>
<8-bit-Number> ::= [0x00..0xFF]
<Text> ::= <Chars> | '"' <SpacedChars> '"'
<SpacedChars> ::= <Chars> | <Chars> ' ' <Chars> | <SpacedChars>
<Chars> ::= <Char> | <Char> <Chars>
<Char> ::= [a..z] | [A..Z] | ' '
<Hex8> ::= [0x00..[0xFF]
<Duation> ::= [0..65535]
<Digit> ::= [0..9]

<Pin> ::= '{' P ' ' N : <Binary> ' ' <Binary> ' ' <Binary> ' ' <Binary> ' ' <Retries> '}'
<Binary> ::= 0 ¦ 1
<Retries> ::= [0..3]

<Constant> ::= '{' C ' ' <ConstantIndex> : <Text> '}'
<ConstantIndex> ::= [0..7]