Merge branch 'dekuNukem:master' into pythonhid

.gitignore

@@ -1,3 +1,5 @@
 *.iml
 .idea
-**/venv/
+**/venv/
+
+firmware/code/MDK-ARM/lul

README.md

@@ -6,9 +6,9 @@
 
 duckyPad is a 15-key mechanical macropad that helps **consolidate and speed up your workflow** by automating keyboard (and mouse!) inputs. 
 
-![Alt text](resources/pics/title.png)
+![Alt text](resources/pics/title_jpg.jpg)
 
-duckyPad features a sleek design and all the goodies of a high-end mechanical keyboard:
+duckyPad has a sleek design and all the goodies of a high-end mechanical keyboard:
 
 * Mechanical switches
 * **Hot-swap**
@@ -27,22 +27,19 @@ But more crucially, duckyPad also features **previously-unseen-in-macropads** in
 
 ![Alt text](resources/pics/teaser.gif)
 
-When pressed, each key executes a user-created *`duckyScript`* to automate keyboard actions:
+When pressed, each key execute a *`duckyScript`* to automate keyboard actions.
 
-![Alt text](resources/pics/header.gif)
-
-The scripts can be as simple as shortcuts like `Control + C`, or as sophisticated as launching applications, managing livestreams, or even [creating root backdoors](https://github.com/hak5darren/USB-Rubber-Ducky/wiki/Payload---OSX-Root-Backdoor) or [grabbing passwords](https://github.com/hak5darren/USB-Rubber-Ducky/wiki/Payload---download-mimikatz%2C-grab-passwords-and-email-them-via-gmail). It's all up to you!
+It can be as simple as shortcuts like `Control + C`, or as complex as launching applications, managing livestreams, or even [creating root backdoors](https://github.com/hak5darren/USB-Rubber-Ducky/wiki/Payload---OSX-Root-Backdoor) or [grabbing passwords](https://github.com/hak5darren/USB-Rubber-Ducky/wiki/Payload---download-mimikatz%2C-grab-passwords-and-email-them-via-gmail). It's all up to you!
 
 ## Join Our Discord!
 
-Feel free to join our [Official Discord](https://discord.gg/4sJCBx5) for discussions, asking questions, sharing scripts, and latest updates!
+Feel free to join our [Official Discord](https://discord.gg/4sJCBx5) for discussions, questions, sharing scripts, and latest updates!
 
-## Get duckyPad on Tindie!
+## Get a duckyPad!
 
-duckyPad is [now available on Tindie!](https://www.tindie.com/products/21984), feel free to grab one there!
+duckyPad is [now available on Tindie](https://www.tindie.com/products/21984), feel free to grab one there!
 
-And thanks to the interest and support from the [amazing people like you](kickstarter_backers.md)
-, the [duckyPad Kickstarter](https://www.kickstarter.com/projects/dekunukem/duckypad-do-it-all-mechanical-macropad) has been a great success! With over 630% funded from 705 backers!
+And thanks to the interest and support from the [amazing people like you](kickstarter_backers.md), the [Kickstarter campaign](https://www.kickstarter.com/projects/dekunukem/duckypad-do-it-all-mechanical-macropad) has been a great success!
 
 Finally, here's a video of duckyPad in action!
 <table>
@@ -58,7 +55,7 @@ Finally, here's a video of duckyPad in action!
 * Per-Key **`RGB Lighting`** 
 * **`OLED Screen`**, showing profile and key names.
 * Powerful multi-line scripting with [duckyScript](duckyscript_info.md).
-* 32 profiles of 15 keys, for a total of 480 scripts.
+* 32 profiles of 15 keys, 480 macros total.
 * [Automatic profile switching](https://github.com/dekuNukem/duckyPad-profile-autoswitcher) based on active window.
 * microSD storage
 * USB-C Connector

app_posix.md

@@ -1,17 +1,57 @@
 # Running duckyPad Configurator on Linux
 
+## Script Install Method
+To use duckyPad configurator, clone the repo or download the latest source files from the [release page](https://github.com/dekuNukem/duckyPad/releases/latest). Enter `pc_software` directory in terminal, then use `duckypad_config_install.sh` file to install the software on your system.
+
+The Install script will move all files to the `/opt/duckypad_config` directory. It will also install the python dependencies and the udev rules. Currently, this has only been tested with Ubuntu based distros.
+
+```bash
+sudo +x ./duckypad_config_install.sh
+./duckypad_config_install.sh
+```
+
+## Manual Install Method
+
 To use duckyPad configurator, clone the repo or download the latest source files from the [release page](https://github.com/dekuNukem/duckyPad/releases/latest). Enter `pc_software` directory in terminal, then use the following commands to install dependencies and launch the app:
 
 ```bash
 cd pc_software
 pip3 install appdirs hidapi
-python3 duckypad_config.py
+
+sudo python3 duckypad_config.py
+
 # OR if using Hi-DPI
-DUCKYPAD_UI_SCALE=2 python3 duckypad_config.py
+sudo DUCKYPAD_UI_SCALE=2 python3 duckypad_config.py
 # adjust the number for best results
 ```
 
-## Udev Rule
+### Arch Linux
+
+Users of Arch Linux can take advantage of `duckypad-git` PKGBUILD in [aur](https://aur.archlinux.org/packages/duckypad-git) which also installs udev rule (below).
+
+```bash
+paru -S duckypad-git
+# replace paru with yay if required
+```
+
+### Ubuntu/Pop!_OS/Linux Mint Users
+
+If the above commands give you errors when attempting to execute `sudo python3 duckypad_config.py` perform the following first:
+
+```bash
+sudo apt install python3-tk
+sudo apt install python3-appdirs
+sudo apt install python3-hid
+pip3 install pyautogui
+```
+
+Ubuntu/Pop!_OS/Linux Mint Users will also need to execute the duckypad_config.py file as non-sudo.
+
+```bash
+python3 duckypad_config.py
+```
+
+### Udev Rule
 
 To enable USB profile editing on Linux, you may need to install a Udev rule to allow your user to access the HID device.
 
@@ -25,7 +65,7 @@ Put the following text into the file, and save.
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="d11c", TAG+="uaccess", TAG+="udev-acl"
 ```
 
-The rule will be applied on the next reboot.
+The rule will be applied once duckyPad is reinserted or after a system reboot.
 
 You can also force a reload of the rules by running:
 

duckyscript_info.md

@@ -8,13 +8,11 @@
 
 duckyScript is a simple scripting language for automating keypresses. It was originally developed for [USB Rubber Ducky](https://shop.hak5.org/products/usb-rubber-ducky-deluxe).
 
-This guide gives an concise overview of duckyScript. For more information, [see this page](https://github.com/hak5darren/USB-Rubber-Ducky/wiki/Duckyscript).
-
 ## Examples
 
-duckyScript is very easy and straightforward to write, you basically just tell it what key to press!
+duckyScript is very straightforward to write, you basically just tell it what key to press!
 
-Let's take a look at some examples first:
+Some quick examples:
 
 ### Open Task Manager
 
@@ -41,14 +39,6 @@ DELAY 600
 CONTROL w
 ```
 
-## Syntax Details
-
-* One command per line. **`Each line has a 256 character limit!`**
-
-* 1000 milliseconds = 1 second.
-
-* Check out the [sample profiles](https://github.com/dekuNukem/duckyPad/tree/master/sample_profiles) for more examples.
-
 ## List of Commands
 
 [REM](#REM)
@@ -61,6 +51,8 @@ CONTROL w
 
 [STRING](#STRING)
 
+[STRINGLN](#STRINGLN)
+
 [REPEAT](#REPEAT)
 
 [Special Keys](#Special-Keys)
@@ -81,9 +73,9 @@ CONTROL w
 
 [GOTO_PROFILE](#GOTO_PROFILE)
 
-[HOLD](#HOLD-experimental)
+[EMUK](#emuk)
 
-[LOOP](#LOOP-experimental)
+[LOOP](#LOOP)
 
 -----
 
@@ -95,7 +87,7 @@ CONTROL w
 
 `DEFAULTDELAY` specifies how long (in milliseconds) to wait between **`each line of command`**.
 
-If unspecified, `DEFAULTDELAY` is 18ms in duckyPad.
+If unspecified, `DEFAULTDELAY` is 18ms.
 
 ```
 DEFAULTDELAY 100
@@ -105,15 +97,15 @@ REM duckyPad will wait 100ms between each subsequent command
 
 ### DEFAULTDELAYFUZZ X
 
-Adds an additional random delay from 0 to X milliseconds after `each line of command`, can be used to make typing more human-like.
+Adds an **additional** random delay from 0 to X milliseconds after `each line of command`, can be used to make typing more human-like.
 
 Set to 0 to disable.
 
 ### DEFAULTCHARDELAY
 
 `DEFAULTCHARDELAY` specifies how long (in milliseconds) to wait between each **`key stroke`**.
 
-If unspecified, `DEFAULTCHARDELAY` is 18ms in duckyPad.
+If unspecified, `DEFAULTCHARDELAY` is 18ms.
 
 ```
 DEFAULTCHARDELAY 50
@@ -123,7 +115,7 @@ REM duckyPad will wait 50ms between each key stroke
 
 ### DEFAULTCHARDELAYFUZZ X
 
-Adds an additional random delay from 0 to X milliseconds after `each key stroke`, can be used to make typing more human-like.
+Adds an **additional** random delay from 0 to X milliseconds after `each key stroke`, can be used to make typing more human-like.
 
 Set to 0 to disable.
 
@@ -147,6 +139,14 @@ STRING Hello world!!!
 REM types out "Hello world!!!"
 ```
 
+**Max `256` characters per line!** Split into multiple lines if longer.
+
+### STRINGLN
+
+Same as above, but presses **enter key** at the end.
+
+Available after [firmware 0.20.2](https://github.com/dekuNukem/duckyPad/blob/master/firmware_updates_and_version_history.md).
+
 ### REPEAT
 
 Repeats the last command **`n`** times.
@@ -160,7 +160,7 @@ REM types out "Hello world" 11 times (1 original + 10 repeats)
 
 ### Special Keys
 
-duckyScript also supports a bunch of special keys:
+duckyScript also supports many special keys:
 
 ```
 CTRL / RCTRL
@@ -192,30 +192,7 @@ END
 MENU
 POWER
 
-F1
-F2
-F3
-F4
-F5
-F6
-F7
-F8
-F9
-F10
-F11
-F12
-F13
-F14
-F15
-F16
-F17
-F18
-F19
-F20
-F21
-F22
-F23
-F24
+F1 to F24
 
 (media keys)
 MK_VOLUP
@@ -233,18 +210,16 @@ KP_ASTERISK
 KP_MINUS
 KP_PLUS
 KP_ENTER
-KP_0
-KP_1
-KP_2
-KP_3
-KP_4
-KP_5
-KP_6
-KP_7
-KP_8
-KP_9
+KP_0 to KP_9
 KP_DOT
 KP_EQUAL
+
+(Japanese input method keys)
+(Available after firmware 0.20.4)
+ZENKAKUHANKAKU
+HENKAN
+MUHENKAN
+KATAKANAHIRAGANA
 ```
 
 Those special keys can be used on their own:
@@ -299,7 +274,7 @@ Scroll mouse wheel `X` lines.
 
 Holds / Releases a key.
 
-Can be character key, modifier key, special key, or even mouse button!
+Can be character or special key.
 
 Example:
 
@@ -311,17 +286,19 @@ KEYUP SHIFT
 
 ### SWCOLOR
 
-You can change the colour of a key on-the-fly with `SWCOLOR` command.
+You can change the color of a key on-the-fly with `SWCOLOR` command.
 
-To change the colour of the **current key**, use `SWCOLOR R G B`:
+To change the color of the **current key**, use `SWCOLOR R G B`:
 
 `SWCOLOR 128 0 0`
 
-To change the colour of a **particular key**, use `SWCOLOR_n R G B`:
+To change the color of a **particular key**, use `SWCOLOR_n R G B`:
 
 `SWCOLOR_1 0 128 0`
 
-* The `R G B` value should between `0` and `255`. 0 being off, 255 brightest.
+* `n` is between 1 and 15 inclusive.
+
+* `R G B` is between `0` and `255` inclusive. 0 off, 255 brightest.
 
 ### DP_SLEEP
 
@@ -341,26 +318,28 @@ Use this command to jump to a particular profile.
 
 `GOTO_PROFILE 3` // jump to profile #3
 
-### HOLD (experimental)
+### EMUK
 
-Holds a key when you press it, and release only when you release it. This command makes duckyPad behave more like a traditional keyboard.
+(Known as `HOLD` **before firmware 0.20.3**)
+
+Emulates a regular key.
+
+It holds a key when you press it, and release only when you release it. Makes it behave more like a traditional keyboard.
 
 Possible uses include push-to-talk voice chat, or WASD gamepad.
 
-`HOLD` command must be followed by a single key, it can be a character or a special key.
+You should only use `EMUK` command **on its own**, i.e. the script should only have a single line of `EMUK` command and **nothing else**.
+
+`EMUK` command can be followed by up to 2 keys, they can be character or special keys.
 
 ```
-HOLD w
+EMUK w
 ```
 ```
-HOLD SHIFT
+EMUK SHIFT
 ```
 
-You should only use `HOLD` command on its own, i.e. the script should only have a single line of `HOLD` command and nothing else.
-
-This command is experimental, if you run into any bugs, [let me know](#questions-or-comments)!
-
-### LOOP (experimental)
+### LOOP
 
 This command allows you to **assign different actions to the same key**.
 
@@ -384,9 +363,21 @@ ENTER
 
 * When you press a key, a counter increments, and the script at the corresponding loop is executed.
 
-* This command is not yet supported with test-run on PC app.
+* Loop and color state should persist through profile switches and reboots [**AFTER FIRMWARE 0.20.0**](firmware_updates_and_version_history.md).
+
+* This command is not supported in test-run on PC app.
+
+### LCR (Loop Counter Reset)
+
+* This command resets the counter for `LOOP` commands.
+
+* `LCR` on its own resets **ALL** loop counters in the **CURRENT PROFILE** to **ZERO**. Effectively making everything start from `LOOP0` again.
+
+* `LCR x` resets key `x` loop counter to ZERO, making that key start from `LOOP0` again. `x` is between 1 to 15.
+
+* `LCR x y` resets key `x` loop counter to `y`, making that key start from `LOOP`y again. `x` is between 1 to 15. `y` is between 0 to 9.
 
-* This command is experimental, if you run into any bugs, [let me know](#questions-or-comments)!
+* Try not to mix `LOOP` and `LCR` commands in the same script, probably won't end well.
 
 ## Table of Contents