/** @file */ /** @page Page_CommandLine The chameleon command line * The Chameleon-Mini enumerates as a CDC-ACM virtual serial interface. * For a high level of compatibility to be both interfaced by a human as well as * a user application, it supports a text-based command line, which can be accessed by using * simple terminal software like hyper-terminal or teraterm. * The serial settings, as in baudrate, stopp and parity bits are ignored * on the Chameleon side. * Note that there is no echo of entered characters at the Chameleon. * * Command structure * ================= * * Each of the following commands can result into 3 actions, * depending on the character that is appended to it. * - `?`: Indicates a request that will always return an information * - `=`: Indicates to set a value on the Chameleon * - ``: Indicates to execute a procedure on the Chameleon with an optional response * * Note that some commands only support a subset of these 3 actions. * * In order to perform the desired command action the command has to be * suffixed with a carriage return (CR, 0D hexadecimal). * In order to be more user-friendly when interfacing the Chameleon with a * serial terminal, support for the backspace (08 hexadecimal) and * escape (1B hexadecimal) key have been added. * Any other control character as defined in the ASCII character set is ignored. * Furthermore the Chameleon does not distinguish between uppercase and lowercase. * * Supported Commands * ================== * * The following list shows the supported commands and how they are used. * Command | Description * --------------------- | ----------- * `VERSION?` | Requests the version of the Chameleon * `RESET` | Resets the Chameleon * `UPGRADE` | Sets the Chameleon into firmware upgrade mode (DFU) * `CONFIG` | Returns a comma-separated list of all supported configurations * `CONFIG?` | Returns the currently used configuration * `CONFIG=` | Sets the current configuration to `` (See @ref Page_Configurations) * `UIDSIZE?` | Returns the size of the current configuration's UID * `UID?` | Returns the currently set UID * `UID=` | Sets a new UID to be used in hexadecimal notation * `READONLY?` | Returns the current state of the read-only mode * `READONLY=[0;1]` | Activates or deactivates the read-only mode (Any writing to the memory is silently ignored) * `MEMSIZE?` | Returns the memory size of the current configuration * `UPLOAD` | Waits for an XModem connection to be established in order to upload a memory dump upto the memory size * `DOWNLOAD` | Waits for an XModem connection to be established in order to download a memory dump with exactly the memory size * `BUTTON` | Returns a comma-separated list of supported button press actions for the button * `BUTTON?` | Returns the currently set button press action for BUTTON0 * `BUTTON=` | Sets the current button press action for BUTTON0 * `SETTING?` | Returns the currently activated setting of the chameleon-mini * `SETTING=` | Sets the active setting of the chameleon-mini * `CLEAR` | Clears the entire memory of the currently activated setting * * Responses * ========= * * Subsequent to ANY send command, the Chameleon responds with a status number and status message, separated by a colon and terminated with a carriage return and line feed (CR+LF, 0D+0A hexadecimal). Status numbers are of a 3 digit decimal format with the first digit showing the severity of the answer. Status numbers beginning with a '1' denote an informational item and those beginning with a '2' denote an error. * Response | Description * ---------------------------- | ----------- * `100:OK` | The command executed successfully * `101:OK WITH TEXT` | The command executed successfully and this answer is appended with an additional line of information, terminated with CR+LF * `110:WAITING FOR XMODEM` | The Chameleon is waiting for an XMODEM connection to establish * `200:UNKNOWN COMMAND` | This command is unknown to the Chameleon * `201:INVALID COMMAND USAGE` | This action is not supported by this command * `202:INVALID PARAM` | The format or value of the given parameter value is invalid * * Accessing the command-line using a terminal software * ==================================================== * In order to have quick access to the Chameleon's command-line without using any complicated software, * we suggest using the TeraTerm terminal emulation software available for windows based operating systems. * * Connecting and setting up * ------------------------- * For establishing a connection to the Chameleon's command line, select File -> New Connection, choose * the virtual serial port of the Chameleon and hit the "OK" button. TeraTerm now tries to open the serial port * and should succeed without any error. * * For easier use of the command-line using a terminal software the local-echo functionality should be activated, * to be able to see what is typed into the chameleon. When using TeraTerm, this can be achieved by selecting * Setup -> Terminal and check "Local Echo". * * Uploading and Downloading dump files * ------------------------------------ * In some configurations of the Chameleon, it is necessary to upload a card dump before it can be accessed by a reader. * For doing so, the relatively simple and widely known XMODEM protocol is used. * * To upload a dump file using TeraTerm, follow these steps. * 1. Enter `UPLOAD` and wait for the `110:WAITING FOR XMODEM` response * 2. Select File -> Transfer -> XMODEM -> Send * 3. In the dialog choose the binary dumpfile to be uploaded and make sure the option "Checksum" is checked in the lower left corner * 4. Hitting the "Open" button will start the transfer. If no error is given to the user, the file has been uploaded sucessfully. * * To download the Chameleon's memory again, follow the instructions above except for using `DOWNLOAD` instead of `UPLOAD` * and the Receive function of TeraTerm * * Note that there is a 10 second timeout after entering `UPLOAD` respectively `DOWNLOAD` * after which the standard command-line is activated again. So try again if the timeout is already * over when the XMODEM transfer is about to start. */