## About

A toolchain to turn a Digistump Digispark device into a cheap USB
Rubber Ducky knock-off with a minimum amount of fuss.  This wouldn't
have been possible without the following projects:

- The official USB Rubber Ducky encoder defining the Duckyscript
  language: <https://github.com/hak5darren/USB-Rubber-Ducky> (unknown
  license)
- The duck2spark converter showing how the encoded payload translates
  to equivalent C++ code: <https://github.com/mame82/duck2spark>
  (unknown license)
- Various Digispark projects written in C using Makefiles:
  <https://github.com/yuvadm/digispark-projects> (GPL3)
- A mapping of Linux key names to USB codes:
  <https://gist.github.com/MightyPork/6da26e382a7ad91b5496ee55fdc73db2>
  (Public Domain)
- The V-USB library: <https://www.obdev.at/products/vusb/index.html>
  (GPL2/3)
- Digistump's Arduino libraries:
  <https://github.com/digistump/DigistumpArduino> (unknown license)

## Installation

Run `chicken-install` inside the project directory.

## Workflow

Run the following inside the project directory:

    plucky -i example.duck -l de -o keyboard.c
    make
    make deploy

## Supported language

Duckyscript is a language resembling BASIC.  Every line contains an
all-caps command followed by arguments.  The following commands are
supported:

- `REM <comment>` / `// <comment>`: Ignore the rest of the line.
- `DEFAULT_DELAY <number>`: Set the default delay between execution of
  commands, measured in milliseconds.  This is mostly useful for
  debugging.
- `DELAY <number>`: Wait for the specified amount of milliseconds.
- `STRING <text>`: Type the specified text, using modifiers when
  needed.  Note that this depends on a correctly set keyboard layout.
- `STRING_DELAY <number> <text>`: Like the `STRING` command, but
  waiting the specified delay in milliseconds between each letter.
- `REPEAT <number>`: Repeat the previous non-repeat command the
  specified number of times.
- `<modifier>... <key>`: Type the specified shortcut by pressing the
  key while holding the specified modifiers.  Modifiers are all-caps
  and may contain underscores and numbers.  Keys may be all-caps (like
  `SPACE`), but also be a number or letter.
- `<key>`: Types the key, specified by its all-caps name which may
  contain underscores and numbers.  Use `STRING` for other keys.

For compatibility with existing Duckyscript payloads, the following
behavior is supported:

- `DEFAULTDELAY` is considered an alias for the `DEFAULT_DELAY`
  command.
- Certain shortcuts may use dashes instead of a space as separator:
  - `CTRL-ALT`
  - `CTRL-SHIFT`
  - `ALT-SHIFT`
  - `ALT-TAB`
  - `COMMAND-OPTION`

## Keyboard layouts

Not everyone is using an US layout on their keyboard.  To make sure
the correct keys are typed, you can pick an alternative keyboard
layout.  The `-l` argument allows you to specify the name of a
built-in layout or path to a layout file.  Use `--list-layouts` to
print a list of built-in layouts or check the
`duckyscript/sparkling/layouts` directory.

The format is a list of S-Expressions, with each S-Expression
describing how a character maps to a sequence of shortcuts.  Each
shortcut can either consist of a symbol (representing a key without
modifier) or a list of symbols (representing a key with modifiers).
This structure allows typing characters by using dead keys and more.

## Incompatibilities and other deficiencies

- Currently only German and American keyboard layouts are supported.
- The interaction between the `DEFAULT_DELAY` and `DELAY` command is
  still unclear to me and most likely incorrect.
- Handling of the `REPEAT` command is most likely different from the
  original.
- Shortcuts only support pressing a regular key with optional
  modifiers whereas the original supports modifier-only shortcuts as
  well.
- More can be found on the bug tracker in due time.