diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e070f3..c1a504a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,11 +3,12 @@ All notable changes to this project will be documented in this file. This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log... ## [unreleased][unreleased] - - Changed `hw slot delete`, now it can always delete from slot. (@augustozanellato) - - Refactor CI pipeline. (@augustozanellato) - - Added offline copy EM card uid for btnpress.(@nemanjan00) - - Added offline copy ic card uid for btnpress.(@xianglin1998) - - Added `hw settings btnpress` to get and set button press function.(@xianglin1998) + - Added initial version of the user guides (@GameTec-live) + - Changed `hw slot delete`, now it can always delete from slot (@augustozanellato) + - Refactor CI pipeline (@augustozanellato) + - Added offline copy EM card uid for btnpress (@nemanjan00) + - Added offline copy ic card uid for btnpress (@xianglin1998) + - Added `hw settings btnpress` to get and set button press function (@xianglin1998) - Added `hw battery` to get battery informartion (@xianglin1998) - Added `hw slot delete` to delete HF or LF out of a HF+LF slot (@augustozanellato) - Changed CLI prompt autocompletion, saved history and internal cmd registration (@szymex73) diff --git a/docs/cli.md b/docs/cli.md index cc73494..7829df9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -10,21 +10,21 @@ There are multiple ways to install the CLI, depending on your OS. Windows users have the choice of 4 options: -#### Proxspace +#### ProxSpace -Using Proxspace to build the CLI is the easiest and most comfortable way to get started. +Using ProxSpace to build the CLI is the easiest and most comfortable way to get started. -1. Download proxspace from the [official github](https://github.com/Gator96100/ProxSpace/releases/latest) +1. Download ProxSpace from the [official GitHub](https://github.com/Gator96100/ProxSpace/releases/latest) 2. [Download 7zip](https://www.7-zip.org/) to extract the archive 3. Install 7zip by double clicking the Installer and clicking `Install` -4. Rightclick on the downloaded archive and select `7zip -> Unpack to "ProxSpace"` +4. Right-click on the downloaded archive and select `7zip -> Unpack to "ProxSpace"` -5. Open a terminal in the proxspace folder. If your on a new windows install you should be able to just rightclick and select `Open in Terminal`. If that option is not visible and the ProxSpace folder is still in your downloads folder, press `win+r` and type `powershell` followed by enter. In Powershell now type `cd ~/Downloads/ProxSpace` +5. Open a terminal in the proxspace folder. If you are on a new Windows install, you should be able to just right-click and select `Open in Terminal`. If that option is not visible and the ProxSpace folder is still in your downloads folder, press `win+r` and type `powershell` followed by enter. In Powershell now type `cd ~/Downloads/ProxSpace` -6. Run the command `.\runme64.bat`. After succesfull completion you should be dropped to the `pm3 ~ $` shell. +6. Run the command `.\runme64.bat`. After successful completion, you should be dropped to the `pm3 ~ $` shell. 7. Clone the Repository by typing `git clone https://github.com/RfidResearchGroup/ChameleonUltra.git` @@ -62,23 +62,23 @@ Coming Soon Coming Soon -#### Build Nativly +#### Build Natively -Building Nativly is a bit more advanced and not recommended for beginners +Building natively is a bit more advanced and not recommended for beginners 1. Download and install [Visual Studio Community](https://visualstudio.microsoft.com/de/downloads/) -2. On the workload selection screen choose the `Desktop development with C++` workload. Click `Download and Install` +2. On the workload selection screen, choose the `Desktop development with C++` workload. Click `Download and Install` -3. Download and install [git](https://git-scm.com/download), when asked, add to your path +3. Download and install [git](https://git-scm.com/download). When asked, add to your path -4. Download and install [cmake](https://cmake.org/download/), again, when asked, add to your path +4. Download and install [cmake](https://cmake.org/download/). Again, when asked, add to your path -5. Download and install [python](https://www.python.org/downloads/), when asked, add to your path (small checkbox in the bottom left) +5. Download and install [python](https://www.python.org/downloads/). When asked, add to your path (small checkbox in the bottom left) 6. Choose a suitable location and open a terminal. Clone the repository with `git clone https://github.com/RfidResearchGroup/ChameleonUltra.git` -7. Change into the binarys folder with `cd ChameleonUltra/software/src` +7. Change into the binaries folder with `cd ChameleonUltra/software/src` 8. Build the required config by running `cmake .` @@ -88,7 +88,7 @@ Building Nativly is a bit more advanced and not recommended for beginners 11. Go into the script folder with `cd ../script/` -12. Create a python virtual enviroment with `python -m venv venv` +12. Create a python virtual environment with `python -m venv venv` 13. Activate it by running `.\venv\Scripts\Activate.ps1` @@ -104,28 +104,28 @@ To run again after installing, just do the following: ### Linux -Coming Soon +*Coming Soon* ### MacOS -Coming Soon +*Coming Soon* ## Usage -When in the CLI, plug in your chameleon and connect with `hw connect`. If this fails, get the Serial Port used by your Chameleon and run `hw connect -p COM11` (Replace `COM11` with your serial port, on linux it may be `/dev/ttyacm0`) +When in the CLI, plug in your Chameleon and connect with `hw connect`. If autodetection fails, get the Serial Port used by your Chameleon and run `hw connect -p COM11` (Replace `COM11` with your serial port, on Linux it may be `/dev/ttyACM0`) -### Common activites: +### Common activities - Change slot: hw slot change -s [1-8] -- More examples coming soon +*More examples coming soon* -### Available Commands: +### Available Commands In `()` is the argument description, `[]` are possible entries for that argument (eg `[1-8]`) | Command ID | Command | Arguments | Description | |:----------:|:----------------:|:-------------------------------------------------------------------------:|:-----------------------------------------:| -| 1020 | hw factory_reset | --i-know-what-im-doing (Make sure you really want to wipe your chameleon) | Returns the Chameleon To factory settings | +| 1020 | `hw factory_reset` | `--i-know-what-im-doing` (Make sure you really want to wipe your Chameleon) | Returns the Chameleon to factory settings | | | | | | | | | | | diff --git a/docs/firmware.md b/docs/firmware.md index ee69638..c5f7622 100644 --- a/docs/firmware.md +++ b/docs/firmware.md @@ -1,79 +1,115 @@ # Firmware -The Chameleons firmware consists of 3 parts, the bootloader, the application and the settings +The Chameleon flash contains several parts: the bootloader and its settings, the application, the user data and the SoftDevice. -NOTE: If your developer searching for the building instructions, look into [development](./development.md) +NOTE: If you are a developer searching for the building instructions, look into [development](./development.md) ## The Bootloader -The bootloader is the lowest level programm running on your Chameleon. It is read only and provides the DFU (**D**evice **F**irmware **U**pgrade) mode. The bootloader being read only also makes it really hard to brick your Chameleon. You enter DFU mode by: +The bootloader is the lowest-level program running on your Chameleon. It is read-only and provides the DFU (**D**evice **F**irmware **U**pgrade) mode. The bootloader being read-only, it makes it really hard to brick your Chameleon. The flash also contains a special section to store bootloader settings required by the nRF to deal with upgrades. This is only a concern for developers. -- Holding down the `B` or `right` button for ~5s, plugging it into a PC while still holding the button, hold for another ~10s and release. -- Issuing `hw dfu` from the CLI +You enter DFU mode by of the following methods: -- Clicking on `Enter DFU mode` in a GUI +1. Physical button -The device stays in dfu mode for ~30s. While in DFU mode, the LEDs 4 and 5 blink alternating green. While in DFU mode you can perform firmware upgrades either via a GUI or the command line: +- Disconnect the Chameleon and wait for it to enter sleep mode +- Hold down the `B` button. If you are using Windows you have to wait about ~5s before next step. +- Plug USB into a PC while still holding the button. If you are using Windows you have to wait about ~10s before next step. +- Then release the button -1. Download NRF Util from the [NRF website](https://www.nordicsemi.com/Products/Development-tools/nrf-util) +2. From CLI + +- Execute the command `hw dfu` + +3. From GUI + +- Click on `Enter DFU mode` + +4. From Shell + +- Execute the script `resource/tools/enter_dfu.py` + +The device stays in DFU mode for ~30s. +While in DFU mode waiting for the update, the LEDs 4 and 5 blink alternatively green. +You can then perform firmware upgrades either via a GUI or the command line: + +1. Download nRF Util from the [nRF website](https://www.nordicsemi.com/Products/Development-tools/nrf-util) 2. Open a Command Line / Terminal on your PC 3. Install the "device" toolkit by running `nrfutil install device` -4. Download the firmware from [the github](https://github.com/RfidResearchGroup/ChameleonUltra/releases), you want the ultra-dfu-app.zip or lite-dfu-app.zip depending on your device (the Devkit in this case is a Ultra) +4. Download the Chameleon firmware from [GitHub](https://github.com/RfidResearchGroup/ChameleonUltra/releases). At the moment it is better to take the *Development release* but beware bugs can occur. Choose `ultra-dfu-app.zip` for the Ultra or the Devkit, and `lite-dfu-app.zip` for the Lite. -5. Put your Chameleon into dfu mode and install the firmware with the following command: `nrfutil device program --firmware ultra-dfu-app.zip --traits nordicDfu`(Keep in mind to change the filename to whatever device your using) +5. Put your Chameleon into DFU mode and install the firmware with the following command: `nrfutil device program --firmware ultra-dfu-app.zip --traits nordicDfu` (keep in mind to change the filename if you are using a Lite). -While flashing firmware the LEDs 4 and 5 should blink blue. Using DFU and performing a firmware update is also how you recover from most device related issues. +Step 5: Alternatively you can connect the Chameleon over USB and use the script `firmware/flash-dfu-app.sh` which will take care of flipping it into DFU mode and flashing it with the adequate firmware. + +While flashing firmware is in progress, the LEDs 4 and 5 should blink fast blue and the firmware update should be finished in a matter of seconds. Using DFU and performing a firmware update also helps recovering from most device-related issues. + +If LEDs 4 and 5 are flashing slow red, it indicates an issue with DFU. Try to unplug and plug again or unplug and wait for it to timeout and try again the whole procedure. ## The Application -The application is the piece of software being loaded by the bootloader. It communicates with the client, emulates, reads and writes cards, drives the LEDs, handles buttons and much more. The application is also writable, its the piece of software being updated via DFU. +The application is the piece of software being loaded by the bootloader. It communicates with the client, emulates, reads and writes cards, drives the LEDs, handles buttons and much more. The application is also writable, it is the piece of software being updated via DFU. -The communication with the application is either done via the CLI or a GUI. Communication can be done over USB or BLE (**B**luetooth **L**ow **E**nergy), altough, at time of writing, only GUIs support BLE. +The communication with the application is either done via the CLI or a GUI. Communication can be done over USB or BLE (**B**luetooth **L**ow **E**nergy), although, at time of writing, only GUIs support BLE. ---- +On boot, the application starts in emulation mode, so it can emulate up to 8 HF tags and up to 8 LF tags (one slot can handle both a HF and a LF). -The communication with the application isnt the easiest but is structured as follows: +The Chameleon can be awaken: -`MAGIC BYTE(0x11) LRC(Magic Byte) COMMAND STATUS(0x00) DATA LRC(COMMAND + STATUS + DATA)` +- by pressing a button +- when it comes close to a HF or LF field, *only if* a card corresponding to that field (HF/LF) is loaded into the active slot. -You build the Packet by first adding 0x11, this is the "Magic Byte" to say that theres something coming. This is followed by the LRC ([**L**ongitudinal **R**edundancy **C**heck](https://en.wikipedia.org/wiki/Longitudinal_redundancy_check)) of the "Magic Byte". Then you put in the command in [Big Endian](https://en.wikipedia.org/wiki/Endianness). Each command gets assigned a unique number (eg: `factoryReset(1020)`), this is what your sending to the device. Append the status, also in Big Endian. The status is always 0x00. Then you add your Data, this could be anything, for example sending the card keys when reading a block. +The white LED labeled RF lights up when it detects a field, again only if the active slot supports it. -For recieving its the exact same in reverse. +In some situations, it can be cumbersome to wait for the boot-up animation. This is configurable, cf e.g. the CLI command `hw settings animation set -h`. ---- +On a new Chameleon (or after a factory reset), 3 slots are defined, slot 1 holding both a HF and a LF: -The application controls the buttons. The behaviour of the buttons is user customizeable via the CLI or a GUI. The default behaviour is the following: +- slot 1 LF: a EM4100 with UID `DEADBEEF88` +- slot 1 HF: a MIFARE Classic 1k with UID `DEADBEEF` +- slot 2 HF: a MIFARE Classic 1k with UID `DEADBEEF` +- slot 3 LF: a EM4100 with UID `DEADBEEF88` -- `A` short press: Slot -1 - -- `B` short press: Slot +1 - -- `A` long press: Copy IC - -- `B` long press: Copy ID - -When a slot is selected the LED shows what type of card is loaded by changing the LEDs color: +When a slot is selected, the LED shows what type of card is loaded with the following color code: - Green: HF card loaded - - Blue: LF card loaded +- Red: Both HF and LF loaded -- Red: Both loaded +When a dual HF/LF slot is activated by an external field, it will turn green or blue according to the frequency. + +The application controls the buttons. The behavior of the buttons is customizable via the CLI or a GUI. The default behavior is the following: + +- `A` short press: Select previous slot + +- `B` short press: Select next slot + +- `A` long press: Copy LF or HF tag UID (only Ultra, not Lite) + +- `B` long press: Copy LF or HF tag UID (only Ultra, not Lite) + +*About UID copy*: the action depends on the current slot support. So to be able to copy an EM4100 LF tag, the slot must be configured firstly to emulate an EM4100 tag. And to be able to copy a HF 14a tag, the slot must be configured for the right type of HF tag. Only the UID will be copied, not the data. The Chameleon also shows the following LED effects: -- Charging: 4 Pulsing green lights +- Charging: 4 pulsing green lights -- CLI / GUI connected over USB: Chasing LEDs in the color of the selected slot (left to right for slots 1-4 and 5-8 chase right to left) +- CLI / GUI connected over USB: Chasing LEDs in the color of the selected slot (left to right for slots 1-4 and right to left for slots 5-8). -The white LED labled RF lights up when it detects a field and a card corrosponding to that field (HF/LF) is loaded into the currently selected slot. +The device enters sleep mode after about 5s unless it is plugged in USB or if a client is connected over BLE. You can use the buttons to wake it up again. You can also press quickly a button during the sleep animation to keep the device awake. -The device enters sleep mode, if no CLI / GUI is connected over BLE or serial, after ~5s. You can use the buttons to wake it up again. -## The Settings +## The SoftDevice -The Chameleon has a reserved space of memory and flash where it stores settings. This will not be overwritten by DFU updates and the settings will only be reset by either issuing `hw factory_reset --i-know-what-im-doing` in the CLI or clicking Factory reset in a GUI. \ No newline at end of file +A [SoftDevice](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52_softdevices.html) is a precompiled and linked binary software implementing a wireless protocol developed by Nordic Semiconductor. + +We are using the [SoftDevice S140](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrf52%2Fstruct%2Fnrf52_softdevices.html) which implements a BLE (Bluetooth® Low Energy) Central and Peripheral protocol stack solution. + +## The User Data + +The Chameleon has a reserved space of memory and flash where it stores application settings, active slot and slots configurations and data. This will not be overwritten by DFU updates and the data will only be reset by either issuing `hw factory_reset --i-know-what-im-doing` in the CLI or clicking `Factory reset` in a GUI. +*Warning:* Settings and/or data might be reset to defaults if you downgrade the firmware version up to a version not supporting the newer format. diff --git a/docs/protocol.md b/docs/protocol.md new file mode 100644 index 0000000..7b1a6a2 --- /dev/null +++ b/docs/protocol.md @@ -0,0 +1,19 @@ +# Protocol description + +**WIP** + +## Packets format + +The communication with the application is not the easiest but is structured as follows: + +`MAGIC BYTE(0x11) LRC(Magic Byte) COMMAND STATUS(0x00) DATA LRC(COMMAND + STATUS + DATA)` + +You build the Packet by first adding 0x11, this is the "Magic Byte" to say that there is something coming. This is followed by the LRC ([**L**ongitudinal **R**edundancy **C**heck](https://en.wikipedia.org/wiki/Longitudinal_redundancy_check)) of the "Magic Byte". Then you put in the command in [Big Endian](https://en.wikipedia.org/wiki/Endianness). Each command gets assigned a unique number (e.g. `factoryReset(1020)`), this is what you are sending to the device. Append the status, also in Big Endian. The status is always 0x00. Then you add your Data, this could be anything, for example sending the card keys when reading a block. + +For receiving, it is the exact same in reverse. + +## Packet payloads + +Each command and response have their own payload formats. + +TODO: