Skip to content

Commit

Permalink
Update README to reflect new packaging (#67)
Browse files Browse the repository at this point in the history
* Update README to reflect new packaging

* code blocks

* Update README.md

Co-authored-by: John Bowser <[email protected]>

Co-authored-by: John Bowser <[email protected]>
  • Loading branch information
zvecr and jgbowser authored Oct 18, 2021
1 parent 0501d04 commit e4f9774
Showing 1 changed file with 25 additions and 20 deletions.
45 changes: 25 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,17 @@

2. Plug in your keyboard.

3. In your terminal, change to the directory where you downloaded the executable and applet-*.bin file(s).
3. In your terminal, change to the directory where you downloaded the executable file.

4. **Windows** - Run `mdloader_windows.exe --first --download FILE_NAME --restart`. Replace "FILE_NAME" with the filename of your compiled firmware.
**Linux** - Run `mdloader_linux --first --download FILE_NAME --restart`. Replace "FILE_NAME" with the filename of your compiled firmware. Depending on your user's permissions, you might have to add your user to the `dialout` group or use `sudo` on the command.
**Mac** - Run `mdloader_mac --first --download FILE_NAME --restart`. If you downloaded with Mac Safari, run `mdloader_mac.dms --first --download FILE_NAME --restart`. Replace "FILE_NAME" with the filename of your compiled firmware.

5. You should see the message:
4. Run the following command:
```
Scanning for device for 60 seconds
./mdloader --first --download FILE_NAME --restart
```
**Note**: Replace `FILE_NAME` with the filename of your compiled firmware.

5. You should see the message:
```
Scanning for device for 60 seconds
.....
```

Expand All @@ -25,7 +27,6 @@ Device port: /dev/cu.usbmodem234431 (SAMD51J18A)
Opening port '/dev/cu.usbmodem234431'... Success!
Found MCU: SAMD51J18A
Bootloader version: v2.18Sep 4 2018 16:48:28
Applet file: applet-flash-samd51j18a.bin
Applet Version: 1
Writing firmware... Complete!
Booting device... Success!
Expand All @@ -42,23 +43,23 @@ Massdrop Loader is used to read firmware from and write firmware to Massdrop key

## Supported operating systems

Windows XP or greater (32-bit and 64-bit versions, USB Serial driver in drv_win folder)
Linux x86 (32-bit and 64-bit versions)
Mac OS X
- Windows XP or greater (32-bit and 64-bit versions, USB Serial driver in drv_win folder)
- Linux x86 (32-bit and 64-bit versions)
- Mac OS X

## Supported devices

Massdrop keyboard's featuring Microchip's SAM-BA bootloader.

## Building

Enter mdloader directory where Makefile is located and excute:
Enter mdloader directory where Makefile is located and execute:

`make`
```
make
```

This will create a `build` directory with the compiled executable and required applet-*.bin files.
Run `./build/mdloader` to test.
Note that the target MCU applet file must exist in the directory the executable is called from.
This will create a `build` directory with the compiled executable. Run `./build/mdloader` to test.

## Usage
```
Expand All @@ -82,20 +83,24 @@ Usage: mdloader [options] ...

To write firmware to the device and restart it:

`mdloader --first --download new_firmware.hex --restart`
```
mdloader --first --download new_firmware.hex --restart`
```

The program will now be searching for your device. Press the reset switch found through the small hole on the back case or by appropriate key sequence to enter programming mode and allow programming to commence.
Firmware may be provided as a binary ending in .bin or an Intel HEX format ending in .hex, but .hex is preferred for data integrity.
Note that safeguards are in place to prevent overwriting the bootloader section of the device.

To read firmware from the device:

`mdloader --first --upload read_firmware.bin --addr 0x4000 --size 0x10000`
```
mdloader --first --upload read_firmware.bin --addr 0x4000 --size 0x10000
```

Where --addr and --size are set as desired.
Where `--addr` and `--size` are set as desired.
Note the output of reading firmware will be in binary format.

Test mode may be invoked with the --test switch to test operations while preventing firmware modification.
Test mode may be invoked with the `--test` switch to test operations while preventing firmware modification.
Test mode also allows viewing of binary data from a read instead of writing to a file.

## Troubleshooting
Expand Down

0 comments on commit e4f9774

Please sign in to comment.