commit ca19786df80b3e94df520920543087ac88ee5373 Author: GameTec_live Date: Mon Mar 31 21:07:53 2025 +0200 feat: Migrate docs diff --git a/.github/workflows/deploy-wiki.yml b/.github/workflows/deploy-wiki.yml new file mode 100644 index 0000000..1763b00 --- /dev/null +++ b/.github/workflows/deploy-wiki.yml @@ -0,0 +1,51 @@ +name: Deploy this repository (wiki) to the wiki repository of ChameleonUltra + +on: + push: + branches: ["main"] + workflow_dispatch: + +jobs: + deploy-wiki: + runs-on: ubuntu-latest + steps: + - name: Checkout source repository + uses: actions/checkout@v4 + with: + path: source-repo + + - name: Checkout wiki repository + uses: actions/checkout@v4 + with: + repository: RfidResearchGroup/ChameleonUltra.wiki + path: wiki-repo + token: ${{ secrets.WIKI_DEPLOY_TOKEN }} + + - name: Copy content to wiki repository + run: | + # Remove everything from wiki except .git directory + find wiki-repo -mindepth 1 -maxdepth 1 -not -name .git -exec rm -rf {} + + + # Copy all files from source to wiki + cp -r source-repo/* wiki-repo/ + + # Debug info + echo "Files to be committed to wiki:" + ls -la wiki-repo + + - name: Commit and push to wiki + working-directory: wiki-repo + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + + # Add all changes + git add . + + # Commit if there are changes + if git diff --staged --quiet; then + echo "No changes to commit" + else + git commit -m "Update wiki content from docs repository" + git push + fi \ No newline at end of file diff --git a/.github/workflows/deploy_to_pages.yml b/.github/workflows/deploy_to_pages.yml new file mode 100644 index 0000000..7cdc612 --- /dev/null +++ b/.github/workflows/deploy_to_pages.yml @@ -0,0 +1,47 @@ +name: Deploy wiki to GitHub Pages with Jekyll + +on: + push: + branches: ["main"] + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..b2c2b27 --- /dev/null +++ b/Home.md @@ -0,0 +1,37 @@ +# Chameleon Ultra Guide + +This guide goal is to guide you through setting up and using your Chameleon Ultra and Lite. + +This Guide is split up into multiple "subguides": + +### About the device + +- [[Whitepaper|technical_whitepaper]]: Discover what the Chameleon Ultra is capable of. + +- [[Hardware|hardware]]: Learn to know the hardware of your Chameleon. + +- [[Firmware|firmware]]: Your Chameleon runs a firmware, learn what it can do and how to use it. + +### Interacting with the device + +- [[Quickstart|quickstart]]: For the impatient people to just get you up and running with anything. + +- [[CLI|cli]]: The official way to control your Chameleon is via the **C**ommand **L**ine **I**nterface (CLI). Learn how to install and master the CLI. + +- [[GUIs|gui]]: Some people also develop **G**raphical **U**ser **I**nterfaces (GUIs), these may be a good start for people that do not want to deal with a CLI. + +- [[Troubleshooting|troubleshooting]]: For when things go wrong, here are some common tips to maybe fix whatever issue you might have. + +### For developers + +- [[Development|development]]: For all developers. This covers how to build firmware from source and set up a development environment. + +- [[SDKs|sdk]]: SDKs for Chameleon, useful if you want to develop your own application to control Chameleon. + +- [[Protocol|protocol]]: The gory details of the communication protocol, useful if you want to develop your own client. + +### Miscellaneous + +- [[Modding|modding]]: Third party moddings worth mentioning. + +- [[FAQ|faq]]: **F**requently **A**sked **Q**uestions, if you have a question, it might already be answered here. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f288702 --- /dev/null +++ b/LICENSE @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/README.md b/README.md new file mode 100644 index 0000000..beca0b0 --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# Chameleon Ultra docs repo + +Everything here will automatically be deployed to the [wiki](https://github.com/RfidResearchGroup/ChameleonUltra/wiki) and other places + +Feel free to contribute! + +Keep in mind the branch protection rules when contributing (pushing to main without a PR is disabled) \ No newline at end of file diff --git a/_Footer.md b/_Footer.md new file mode 100644 index 0000000..8e977c1 --- /dev/null +++ b/_Footer.md @@ -0,0 +1 @@ +Chameleon Ultra - [GPLV3 Licensed](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/LICENSE) - Made with ❤️ by the community \ No newline at end of file diff --git a/chameleonultragui.md b/chameleonultragui.md new file mode 100644 index 0000000..f3c5bd5 --- /dev/null +++ b/chameleonultragui.md @@ -0,0 +1,150 @@ +## Get ChameleonUltraGUI + +- [on Google Play](https://play.google.com/store/apps/details?id=io.chameleon.ultra) / [APK](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/apk.zip) +- [on iOS](https://apps.apple.com/dk/app/chameleon-ultra-gui/id6462919364) +- [on Windows](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/windows-installer.zip) ([or without installer](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/windows.zip)) +- [on Linux](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/linux.zip) +- [on macOS](https://apps.apple.com/app/chameleon-ultra-gui/id6462919364) + +## Page Breakdown + +### Homepage +![CUGUI Homepage](./images/cugui-homepage.png) + +Starting from the top left, you find + +- the *Device Name*: `Chameleon Ultra` or `Chameleon Lite` depending on the device connected ; +- the *Disconnect* button: pressing this icon cleanly disconnects the Chameleon. It is recommended to use this button whenever possible ; +- the *Connected Port*: it tells you where and how the chameleon is connected, followed by how it is connected (*Connection Method*), which displays a USB or Bluetooth icon ; +- the *Battery Charge* icon: you can press it long to get more details. Note that it is refreshed only when reopening the Homepage ; +- the *Used Slots*: it displays how many out of the 8 slots are used ; +- the *Slot Changer*: the currently selected slot is highlighted with a red circle, while enabled slots are filled in. Everything else is a hollow circle. The arrows left and right allow you to change the currently selected slot ; +- the *Firmware version*: the version is pulled from the device displayed, as well as git commit information ; +- the *Check for updates* button: it compares the firmware with the one available on GitHub and then updates if a newer version is available ; +- the *Switch mode* button: use it to switch between reader and emulator modes. The icon will update accordingly ; +- the *Device Setting* button: it allows you to change settings concerning the device, like changing the animation mode. + +### Device settings +![Device Settings](./images/cugui-devicesettings1.png) +![Device Settings2](./images/cugui-devicesettings2.png) + +Top to bottom: +- *Enter DFU mode*: to enter the device DFU mode. Allows the user to take over ; +- *Flash latest FW via DFU*: download the newest firmware from GitHub, disregarding if the device is already up to date, and flash it ; +- *Flash .zip FW via DFU*: it allows the user to select a zip they would like to flash to the device ; +- *Animations*: choose if the device should play the boot-up animation when woken up by an external RFID field ; +- *Button config*: it allows you to define both short-press and long-press actions +- *BLE pairing* toggle: you can decide whether pairing with a BLE PIN is required or not. Enabling PIN increases security at the loss of convenience. You can define a *BLE PIN* once pairing is enabled and you can force forgetting about existing pairings with the *Clear bounded devices* option. +- *Reset settings*: it resets all device settings but does not wipe user data. +- *Factory reset*: **IT WIPES ALL USER DATA** and resets the device to factory settings. + +### Slot Manager +![Slot Manager](./images/cugui-slotmanager.png) + +The *Slot Manager* consists of 8 cards representing the 8 slots on the device. + +The *RFID icon* in the top left corner can either be green or red, meaning the slot is enabled and disabled respectively. + +The *Credit Card icon* displays the name and card type of the HF card in the slot. +The *Wi-Fi icon*, on the other hand, displays the name and card type of the LF card in the slot. + +The *Gear icon* opens the slot settings. These settings can be changed per slot. + +The entire card is also one big button, pressing anywhere on the card opens the select dialog for loading a card. + +### Slot Settings +![Slotsettings](./images/cugui-slotsettings1.png) +![Slotsettings2](./images/cugui-slotsettings2.png) + +The two rows at the top, labeled HF and LF respectively, display the names of the currently loaded cards. Next to them, the *X* clears them out of the slot. If both are empty, the slot will automatically be disabled. + +Under *Slot Status* you can set if the slot is enabled or disabled. + +The *Mifare Classic emulator settings* section allows you to toggle various behaviors: +- *Gen1A Magic Mode*: behaves like a gen1a magic card and allows writing to it using magic commands like the Proxmark3 `cload` ; +- *Gen2 Magic Mode*: behaves like a gen2 magic card, makes Block 0 writable ; +- *Use UID/SAK/ATQA from 0 block*: the Chameleon Ultra stores the UID and other anti-collision data independently of the card content. Enabling this setting tells the Chameleon to derive them from card content block 0. Only for MFC with 4-byte UID ; +- *Collect nonces (Mfkey32)*: it toggles nonce collection for mfkey32. When enabled you will be prompted to present the Chameleon to a reader. After you have collected nonces the *Present Chameleon to reader* message will change into a *Recover Keys from x nonces* button. Pressing this will start the recovery process ; +- *Write mode*: Please refer to the [[firmware docs|firmware]]. + +### Search dialog +![Search Dialog](./images/cugui-searchdialog.png) + +When using the GUI you may encounter a *Search* dialog. The dialog is structured as follows: + +Top left you find the *Back* button, this will abort the selection and bring you back. + +Near the end of the row, if it is a card search dialog, a filter option will show. This allows you to filter between *HF*, *LF* and *All* cards. + +At the end you find a *X*, this X will clear the query. + +You enter the query into the *textbox* on the top with the placeholder text "Search" + +The search results get listed below. The Card or Wi-Fi symbol indicates if it is LF/HF. The color of the Icon is the user-defined color. + +Listed also are the name and type. + +Selecting the entry automatically closes the search. + +### Saved Cards +![Saved Cards](./images/cugui-savedcards.png) + +The *Saved Cards* page allows you to manage your cards and dictionaries. + +You import a card or dictionary by clicking the *+* button in their respective half. This opens a select dialog. You may then either select a CUGUI Json file or a Bin file. A Json file gets imported immediately while a Bin file asks if the supplied data is correct before saving. + +Once again, we got a card per card or dictionary. At the left you find the Icon for HF/LF with the user-defined color. To the left of that the card name, type and quick actions for edit, export and delete. + +The Card is again one Big button, pressing it brings up the Slot info. It displays info about the selected item and also has the quick actions present at the bottom. + +![Card Info](./images/cugui-savedcardinfo.png) + +### Card Edit Menu +![HF Card edit](./images/cugui-editcard-HF.png) +![LF Card edit](./images/cugui-editcard-LF.png) + +Depending on the selected card type the menu only displays options applicable to it. +At the top of the menu is the name and icon. Pressing on the icon allows you to change the color. + +Right below is the drop-down for the type. You may switch between any type at will. + +A bit lower again you find the UID, SAK, ATQA, ATS and all other options for the selected type. This form auto-validates, so you should not be able to save a invalid config. + +And finally at the bottom are the save and cancel options, to save the changes and exits, or to cancel the operation with no changes. + +### Settings +![Settings](./images/cugui-settings.png) + +The App settings have their own page and consist of a few simple settings: +- *Sidebar Expansion*: Whether or not the sidebar shall be expanded or if the windows size should decide that +- *Theme*: Light/Dark or get it from the System +- *Color Scheme*: Allows you to choose a color you like for the app +- *Language*: Choose any of the languages available. Translating is done via our Crowding project. +- *About*: Displays simple info about the app, such as build number, contributors and people who have donated on Opencollective +- *Activate debug mode*: Don't, just Don't + +## How to use MFKEY32 + +- set slot to MIFARE Classic (by uploading an empty dump) +- enable mfkey32 for that slot (toggle in slot settings) +- select slot and present ultra repeatedly to the reader in order to collect nonces +- after collecting some nonces, go back into slot settings and click recover keys + +## Troubleshooting + +### Font scaling issues on HiDPI screens + +If you have font scaling issues (tiny fonts) with the Linux desktop app and a HiDPI screen, you can solve it by running the app as +``` +GDK_SCALE=2 GDK_DPI_SCALE=0.5 /usr/local/lib/chameleonultragui/chameleonultragui +``` + +### Key recovery from this card is not yet supported +This error may occur when the card you are trying to recovery keys from is requiring a not yet supported recovery technology. You cannot tell the required recovery method from the outside. + +You may be able to solve this issue by dumping the card with a Proxmark3 or Mifare Classic Tool (Mobile App) and then importing a bin file. + +### Error: Invalid data length +This error may occur on windows devices and seems to be a deeper bug in the serial library. + +Reconnecting the device may solve it, also make sure that the App and Firmware are up to date. \ No newline at end of file diff --git a/cli.md b/cli.md new file mode 100644 index 0000000..03e6ee1 --- /dev/null +++ b/cli.md @@ -0,0 +1,211 @@ +# CLI + +The CLI (**C**ommand **L**ine **I**nterface) is the official way to control your Chameleon. + +It requires at least **Python 3.9** version. + +## Installing + +There are multiple ways to install the CLI, depending on your OS. + +### Windows + +Windows users have the choice of 4 options: + +#### ProxSpace + +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) + +2. [Download 7zip](https://www.7-zip.org/) to extract the archive + +3. Install 7zip by double clicking the Installer and clicking `Install` + +4. Right-click on the downloaded archive and select `7zip -> Unpack to "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 successful completion, you should be dropped to the `pm3 ~ $` shell. + +7. Clone the Repository by typing `git clone https://github.com/RfidResearchGroup/ChameleonUltra.git` + +8. Now go into the newly created folder with `cd ChameleonUltra/software/src` + +9. Prepare for package installation with `pacman-key --init; pacman-key --populate; pacman -S msys2-keyring --noconfirm; pacman-key --refresh` + +10. Proceed by installing Ninja with `pacman -S ninja --noconfirm` + +11. Build the required config by running `cmake .` + +12. And the binaries with `cmake --build .` + +13. Go into the script folder with `cd ~/ChameleonUltra/software/script/` + +14. Install python requirements with `pip install -r requirements.txt` + +15. Finally run the CLI with `python chameleon_cli_main.py` + +To use after installing, just do the following: + +1. Run `runme64.bat` + +2. Go into the script folder with `cd ~/ChameleonUltra/software/script/` + +3. Run the CLI with `python chameleon_cli_main.py` + +#### WSL2 + +Coming Soon + +#### WSL1 + +Coming Soon + +#### Build Natively + +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` + +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 + +5. Download and install [python](https://www.python.org/downloads/). When asked, add to your path (small checkbox in the bottom left). Python 3.9 or above is required. + +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 binaries folder with `cd ChameleonUltra/software/src` + +8. Build the required config by running `cmake .` + +9. And the binaries with `cmake --build .` + +10. Copy the binaries by running `cp -r ../bin/Debug/* ../script/` + +11. Go into the script folder with `cd ../script/` + +12. Create a python virtual environment with `python -m venv venv` + +13. Activate it by running `.\venv\Scripts\Activate.ps1` + +14. Install python requirements with `pip install -r requirements.txt` + +15. Finally run the CLI with `python chameleon_cli_main.py` + +To run again after installing, just do the following: + +1. Activate venv by running `.\venv\Scripts\Activate.ps1` + +2. Run the CLI with `python chameleon_cli_main.py` + +### MacOS + +Requires [Homebrew](https://brew.sh/) to be installed. + - If you don't have Homebrew installed on your macOS, open the Terminal and run: + `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` + +See Linux/Macos instructions below for the rest. + +### Linux / MacOS + +Install the dependencies + - Ubuntu / Debian: + `sudo apt install git cmake build-essential python3-venv` + - Arch: + `sudo pacman -S git cmake base-devel python3` + - MacOS: + `brew install git cmake python3` + +Python 3.9 or above is required. + +Run the following script to clone the Repository, compile the tools and install Python dependencies in a virtual environment. + +```sh +#!/bin/bash + +git clone https://github.com/RfidResearchGroup/ChameleonUltra.git +( + cd ChameleonUltra/software/src + mkdir -p out + ( + cd out + cmake .. + cmake --build . --config Release + ) +) +( + cd ChameleonUltra/software/script + python3 -m venv venv + source venv/bin/activate + pip3 install -r requirements.txt + deactivate +) +``` + +To run the client after installing, do the following: + +```sh +cd ChameleonUltra/software/script +source venv/bin/activate +python3 chameleon_cli_main.py +deactivate +``` + +## Usage + +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`) + +### MFKEY32v2 walk-through +Make sure to be in the `software/` directory and run the Python CLI from there. + +```sh +# Connect to the CLI +hw connect +# Check which slot can be used +hw slot list +# Change the slot type, here using slot 8 for a MFC 1k emulation +hw slot type -s 8 -t MIFARE_1024 +# Init the slot content +hw slot init -s 8 -t MIFARE_1024 +# or load an existing dump and set UID and anticollision data, +# cf 'hf mf eload' and 'hf mf econfig' +# Enable the slot +hw slot enable -s 8 --hf +# Change to the new slot +hw slot change -s 8 +# Activate the authentication logs +hf mf econfig --enable-log +``` +Now disconnect, go to a reader and swipe it a few times + +Come back + +```sh +# connect to the CLI +hw connect +# See if nonces were collected. We need 2 nonces per key to recover +hf mf elog +# Recover the key(s) based on the collected nonces +hf mf elog --decrypt +# Clean the logged detection nonces +hf mf econfig --disable-log +``` + Output example: +``` + - MF1 detection log count = 6, start download. + - Download done (144bytes), start parse and decrypt + - Detection log for uid [DEADBEEF] + > Block 0 detect log decrypting... + > Block 1 detect log decrypting... + > Result --------------------------- + > Block 0, A key result: ['a0a1a2a3a4a5', 'aabbccddeeff'] + > Block 1, A key result: ['010203040506'] + +``` + + +*More examples coming soon* diff --git a/development.md b/development.md new file mode 100644 index 0000000..33c295b --- /dev/null +++ b/development.md @@ -0,0 +1,376 @@ +# Development + +In this file you can look up how to [install requirements](#Prerequisites-for-compiling), [edit](#Editing-the-code), [compile](#Compiling-the-code) and [debug](#Debugging-the-code) the firmware! + +## Prerequisites for compiling + +### install a cross-compiler + +So far, the following compilers have been reported to work fine. +Download one of them and decompress it. +Remember the path where you installed it. + +- [gcc-arm-none-eabi-10.3-2021.10](https://developer.arm.com/downloads/-/gnu-rm) +- [arm-gnu-toolchain-12.2.rel1-XXX-arm-none-eabi](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), e.g. [arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz](https://developer.arm.com/-/media/Files/downloads/gnu/12.2.rel1/binrel/arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi.tar.xz) for a x86_64 Linux host + +Always use the official versions from ARM, *DO NOT* install `gcc-arm-none-eabi` from Debian/Ubuntu. +For some unknown reasons, same gcc version from Debian creates a bootloader too large to fit in the allocated flash space. +Moreover it does not contain the `gdb` debugger. + +### install make + +* **Debian/Ubuntu alike** + * Open a terminal. + * Run the following command to install Make: `sudo apt-get install build-essential` +* **Windows using Chocolatey:** + * Open a PowerShell terminal with administrator privileges. + * If not yet installed, run the following command to install Chocolatey: + ``` Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) ``` + * In the same PowerShell terminal, run the following command to install Make using Chocolatey: `choco install make` +* **macOS:** + * Open a terminal. + * If not yet installed, install Homebrew package manager by running the following command: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` + * Once Homebrew is installed, run the following command to install Make: `brew install make` + +### install nRF tools + +- Install nRF Util tool [nrfutil](https://www.nordicsemi.com/Products/Development-tools/nrf-util) + - Move it to a known path like `C:\nrfutil\` or `/usr/local/bin/` + - Add this path to the `PATH` Environment Variable if not yet there. +- Install nRF Util packages: + - `nrfutil install completion device nrf5sdk-tools trace` +- Install [nRF Command Line Tools](https://www.nordicsemi.com/Products/Development-tools/nrf-command-line-tools/download) to get `nrfjprog`, `mergehex` etc. + +### install programmer tools + +Depending on the hardware programmer you want to use, additional tools are needed. + +- If you are using a J-Link: + + - Install [Segger J-Link Software](https://www.segger.com/downloads/jlink) + - alternatively, you can use openocd as described below + - Note: a JLink OB (or a STLink reflashed as a JLink OB) will not work on a nRF. + +- If you are using a ST-Link V2: + + - Install [openocd](https://openocd.org/pages/getting-openocd.html) + - If under Windows, install [ST-Link drivers](https://www.st.com/en/development-tools/stsw-link009.html), extract the zip and run `dpinst_amd64.exe` + +### configure the project + +- Edit `Makefile.defs`: + - Change `GNU_INSTALL_ROOT` (path of previously installed Compiler `bin` folder) + - Change `GNU_VERSION` (Version of the installed Compiler) (FIXME: is it really used?) + - Change the other paths to match your system if needed + - Don't forget to remove the `#` in front of the changed lines +- Alternatively, if you are committing often code, it may be easier to leave `Makefile.defs` intact and to invoke `make` with the desired variables from a script, e.g. `make GNU_INSTALL_ROOT=../../../arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/` + +## Editing the code + +You can use [Visual Studio Code](https://code.visualstudio.com/download) to edit this project! Simply download and +install it! + +- Install the [C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) in VS-Code. +- Install + the [C++ Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack) in + VS-Code. +- Create a new IntelliSense Configuration: + - press F1 in VS-Code and enter `C/C++: Edit Configurations (UI)` + - Add a new Configuration and name it + - Specify your Compiler path (path of previously installed Compiler `bin` folder) + - Change IntelliSense mode to `gcc-arm (legacy)` + - Add include path `${workspaceFolder}/**` + +## Compiling the code + +- Install prerequisites (for instructions have a look at [Prerequisites for compiling](#Prerequisites-for-compiling)) +- Run `build.sh` or try to execute its steps manually if your platform is not yet properly supported. Feedback is always welcome. + +The script produces several images in `objects`. + +* `fullimage.hex` to be used with a programmer over the SWD pins +* `dfu-app.zip` and `dfu-full.zip` to be used with DFU mode + +## Uploading the code in DFU mode + +If the bootloader and the SoftDevice are already properly installed on the Chameleon, you can reflash it directly over DFU. + +To set the device in DFU mode: + +* you can use the Python client and issue the command `hw dfu` +* you can use the script `resource/tools/enter_dfu.py` that does exactly the same but may be easier to call from your scripts +* you can unplug the device, wait for it to sleep, then press the button B and plug it. If the application is bogus, this is the only way. + +The LEDs 4 & 5 should blink green when in DFU mode. + +To flash only the application (safer): + +`nrfutil device program --firmware objects/dfu-app.zip --traits nordicDfu` + +To flash everything (be sure to also have a JLink or ST-Link V2 programmer if something goes wrong): + +`nrfutil device program --firmware objects/dfu-full.zip --traits nordicDfu` + +Under Linux you can use the scripts `flash-dfu-app.sh` and `flash-dfu-full.sh`, they will put the device in DFU mode and flash it. + +## Uploading the code with a programmer + +Connect pins GND, SWC (swclk) and SWD (swdio) to your programmer. + +With a JLink and `nrfjprog` + +``` +# application only: +nrfjprog -f nrf52 --program objects/application.hex --sectorerase --verify --reset +# full: +nrfjprog -f nrf52 --program objects/fullimage.hex --sectorerase --verify --reset +``` + +With a JLink and `openocd` + +``` +# application only: +openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown" +# full: +openocd -f interface/jlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown" +``` + +With a ST-Link V2 and `openocd` + +``` +# application only: +openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/application.hex verify reset ; shutdown" +# full: +openocd -f interface/stlink.cfg -f target/nrf52.cfg -c "program objects/fullimage.hex verify reset ; shutdown" +``` + +## Uploading the code over BLE + +If you are adventurous it is possible to flash the device over BLE (DFU mode). + +To put the device in DFU mode + +* you can use the Python client and issue the command `hw dfu` **TODO:** this will be possible only when the client will be able to work over BLE... +* you can use the script `resource/tools/enter_dfu_over_ble.py` + +Once in DFU mode, the device will announce itself over BLE as `CU-xxxx` where xxxx are the last 2 bytes of the Device Serial Number. + +Then use the official [nRF Device Firmware Update](https://www.nordicsemi.com/Products/Development-tools/nRF-Device-Firmware-Update) mobile application to flash one of the DFU images. + +## Debugging the code from VSCode + +- Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) VS-Code Extension +- Open `app_main.c` +- Open the extension with `CTRL-SHIFT-D` +- Klick on `create a launch.json file` +- Select `Cortex-Debug` +- Add this in the configuration bracket: + +``` +{ + "cwd": "${workspaceFolder}", + "executable": "${workspaceRoot}/firmware/objects/bootloader.out", + "name": "Debug with JLink", + "request": "launch", + "type": "cortex-debug", + "runToEntryPoint": "main", + "showDevDebugOutput": "none", + "servertype": "jlink", + "device": "nrf52", + "interface": "swd", + "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd", +}, +{ + "cwd": "${workspaceFolder}", + "executable": "${workspaceRoot}/firmware/objects/bootloader.out", + "name": "Debug with STLink", + "request": "launch", + "type": "cortex-debug", + "runToEntryPoint": "main", + "showDevDebugOutput": "none", + "servertype": "openocd", + "device": "nrf52", + "svdFile": "${workspaceRoot}/firmware/nrf52_sdk/modules/nrfx/mdk/nrf52.svd", + "gdbPath": "C:/Program Files (x86)/GNU Arm Embedded Toolchain/10 2021.10/bin/arm-none-eabi-gdb.exe", + "configFiles": [ + "interface/stlink.cfg", + "target/nrf52.cfg" + ] +} +``` + +- If you are jlink probe, create `settings.json` in {projectRoot}/.vscode directory. + +``` +{ + "cortex-debug.armToolchainPath": "C:\\UserProgram\\arm_gcc\\none\\bin", + "cortex-debug.JLinkGDBServerPath": "C:\\Program Files\\SEGGER\\JLink\\JLinkGDBServerCL.exe", +} +``` + +- To change `executable` target in `launch.json` to `application` or `bootloader` +- In the debug menu you can select `Debug with JLink` or `Debug with STLink` + +## Debugging the code with gdb and openocd + +See first if you can execute `arm-none-eabi-gdb` from the installed tools. + +* gcc-arm-none-eabi-10.3-2021.10 gdb requires `libncurses5` +* arm-gnu-toolchain-12.2.rel1 gdb requires Python 3.8 + +In case Python 3.8 is not available anymore on your distro, to install a local copy you can do + +``` +wget https://www.python.org/ftp/python/3.8.17/Python-3.8.17.tgz +tar zxvf Python-3.8.17.tgz +cd Python-3.8.17 +./configure --prefix=$HOME/opt/python-3.8.17 --enable-shared +make +rm -rf ~/opt/python-3.8.17 +make install +``` + +Connect openocd to the device with a JLink or a ST-Link V2 + +``` +openocd -f interface/jlink.cfg -f target/nrf52.cfg +``` + +``` +openocd -f interface/stlink.cfg -f target/nrf52.cfg +``` + +Then run gdb as follows + +``` +PYTHONHOME=~/opt/python-3.8.17/ arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi/bin/arm-none-eabi-gdb +``` + +and tell gdb to connect to openocd + +``` +target extended-remote localhost:3333 +``` + +## BlackMagicProbe with RTT support, out of a ST-Link V2 + +You can reflash a ST-Link V2 to use it as a BlackMagicProbe, to get support for RTT and see NRF_LOG messages. +Some clones have only 64kb, this is too short. +Even 128kb is too small when enabling RTT, but we can comment parts of the BMP source code. + +``` +git clone --recursive git@github.com:blackmagic-debug/stlink-tool.git +( cd stlink-tool && make ) +``` + +Then put the `stlink-tool` binary in your path. + +Get [BMP full sources](https://github.com/blackmagic-debug/blackmagic/releases) + +Comment out all probes except Nordic nrf51 in `src/target/cortexm.c` big switch for probes. It should remain + +```c + switch (t->designer_code) { + case JEP106_MANUFACTURER_NORDIC: + PROBE(nrf51_probe); + break; + } +``` + +``` +make -j PROBE_HOST=stlink ST_BOOTLOADER=1 ENABLE_RTT=1 +``` + +Then flash the ST_Link V2 + +``` +stlink-tool src/blackmagic.bin +``` + +See [src/platforms/stlink/README.md](https://github.com/blackmagic-debug/blackmagic/blob/main/src/platforms/stlink/README.md) for more details. +Unplug/plug. +Every time you plug the ST-Link, you have to run `stlink-tool` to enable BMP. +Under linux, it is convenient to install [udev rules](https://github.com/blackmagic-debug/blackmagic/blob/main/driver/README.md#99-blackmagic-plugdevrules) to get aliases `/dev/ttyBmpGdb` and `/dev/ttyBmpTarg`. + +Note that using a native ST-Link V2 with BlackMagicProbe "hosted" will not allow to see NRF_LOG messages. + +## Debugging the code with gdb and BMP with RTT to monitor NRF_LOG + +Assuming you have a BlackMagicProbe with RTT support made out of a ST-Link V2. + +RTT usage: https://black-magic.org/usage/rtt.html + +``` +stlink-tool +sleep 1 +screen /dev/ttyBmpTarg +``` + +In another terminal + +``` +$ arm-none-eabi-gdb +(gdb) target extended-remote /dev/ttyBmpGdb +(gdb) monitor swdp_scan + 1 Nordic nRF52 M4 + 2 Nordic nRF52 Access Port. +(gdb) attach 1 +(gdb) monitor rtt +``` + +We are now able to use gdb and see the NRF_LOG messages on the other terminal. + +## Using JLink with RTT to monitor NRF_LOG + +cf https://embeddedexplorer.com/nrf52-nrf-log-tutorial/ + +``` +JLinkExe -if SWD -device nrf52 -speed 4000 -autoconnect 1 +``` + +in a second terminal: + +``` +JLinkRTTClient +``` + +For Windows add these lines to the `tasks.json`: +```json + { + "label": "logs", + "type": "shell", + "command": "C:\\WINDOWS\\System32\\cmd.exe", + "args": ["/K", "C:\\Program Files\\SEGGER\\JLink\\JLinkRTTClient.exe"], + "options": { + "cwd": "C:\\Program Files\\SEGGER\\JLink" + }, + "problemMatcher": [] + }, + { + "label": "logger server", + "type": "shell", + "command": "C:\\WINDOWS\\System32\\cmd.exe", + "args": ["/K", "C:\\Program Files\\SEGGER\\JLink\\JLink.Exe", "-if", "SWD", "-device", "nrf52", "-speed", "4000", "-autoconnect", "1"], + "options": { + "cwd": "C:\\Program Files\\SEGGER\\JLink" + }, + "problemMatcher": [] + }, +``` + + +## Using SWO pin as UART to monitor NRF_LOG + +One can set `NRF_LOG_UART_ON_SWO_ENABLED := 1` in `Makefile.defs` to activate this functionality. +When activated, NRF_LOG will be available if one connects a UART bridge to the SWO pin which will work as a UART TX pin. +UART works at 115200 bauds. E.g. one can use a FTDI dongle and `screen /dev/ttyUSB0 115200`. +Contrary to RTT that needs to be activated by a JTAG probe, UART logs are immediately available. + +Limitations: + +* SWO pin is shared with... SWO so when e.g. reflashing the device, garbage may appear on the monitoring terminal. +* SWO pin is also shared with the blue channel of the RGB slot LEDs, so faint blue may appear briefly when logs are sent and LED might not work properly when supposed to be blue. + +# Resources + +* [nRF52840 Objective Product Specification v0.5.1](https://infocenter.nordicsemi.com/pdf/nRF52840_OPS_v0.5.1.pdf) diff --git a/faq.md b/faq.md new file mode 100644 index 0000000..e69de29 diff --git a/firmware.md b/firmware.md new file mode 100644 index 0000000..d651739 --- /dev/null +++ b/firmware.md @@ -0,0 +1,120 @@ +# Firmware + +The Chameleon flash contains several parts: the bootloader and its settings, the application, the user data and the SoftDevice. + +NOTE: If you are a developer searching for the building instructions, look into [[development|development]] + +## The Bootloader + +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. + + +You enter DFU mode by of the following methods: + +1. Physical button + +- Disconnect the Chameleon and wait for it to enter sleep mode +- Hold down the 🅑 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 + +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 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 if you are using a Lite). + +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, 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), 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 Chameleon can be awaken: + +- 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. + +The white LED labeled RF lights up when it detects a field, again only if the active slot supports it. + +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 -h`. + +On a new Chameleon (or after a factory reset), 3 slots are defined, slot 1 holding both a HF and a LF: + +- slot 1 LF: a EM4100 with UID `DEADBEEF88` +- slot 1 HF: a MIFARE Classic 1k with UID `DEADBEEF` +- slot 2 HF: a MIFARE Classic Ultralight with UID `04689571FA5C64` +- slot 3 LF: a EM4100 with UID `DEADBEEF88` + +When a slot is selected, the LED shows what type of card is loaded with the following color code: + +- 🟢 HF card loaded +- 🔵 LF card loaded +- 🔴 Both HF and LF 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: + +- 🅐 short press: Select previous slot + +- 🅑 short press: Select next slot + +- 🅐 long press: Copy LF or HF tag UID (only Ultra, not Lite) + +- 🅑 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 + +- 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 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. + +## Write Modes +- **Normal**: Behaves like any normal card +- **Denied**: Read-only card, send NACK to write attempts +- **Deceive**: Accepts write commands but don't change any data (reader thinks write was successful but when reading back, nothing changed) +- **Shadow**: Accepts writes but reverts changes when device goes to sleep (reader can read and write like a normal card but changes are kept in RAM and are lost when the chameleon goes to sleep) + +## The SoftDevice + +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 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 --force` 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/gui.md b/gui.md new file mode 100644 index 0000000..59f952a --- /dev/null +++ b/gui.md @@ -0,0 +1,8 @@ +# GUIs + +There are multiple GUIs to control your Chameleon, two are featured in this documentation. +Note that in spite of what their name may suggest, all GUIs support both the Ultra and the Lite. + +- [[Chameleon Ultra GUI|chameleonultragui]] ([github](https://github.com/GameTec-live/ChameleonUltraGUI)) + +- [MTools Lite for iOS](https://shop.mtoolstec.com/mifare-classic-tool-for-ios) diff --git a/hardware.md b/hardware.md new file mode 100644 index 0000000..fe90159 --- /dev/null +++ b/hardware.md @@ -0,0 +1,51 @@ +# Hardware + +The Chameleon comes in 3 Hardware variants, the Ultra, the Lite and the Devkit. + +## The Ultra + +The Chameleon Ultra comes in a black box with gold printing. This box has the following dimensions: 9.5 cm x 5.5 cm x 3.5 cm + +![box.png](./images/ultra-box.jpg) + +The Box contains a foam pad, a USB cable that has a removable end to convert it to USB-C, a Proxgrind 3.5 hex screwdriver, 2 replacement screws and a keychain and the device itself. + +![box-contents.jpg](./images/ultra-box-contents.jpg) + +The device itself features 4 screws holding it together, 2 buttons labeled `A` and `B`. The device consists of 2 PCBs (**P**rinted **C**ircuit **B**oards) and a plastic spacer, one contains the Electronic and the HF (**H**igh **F**requency), 13.56 MHz, antenna as well as the 8 LEDs indicating which slot is currently active and the other board features the Chameleon Ultra text, the screws and the LF (**L**ow **F**requency), 125KHz, antenna. The plastic spacer houses the battery as well as the ferrite pad which enables HF and LF emulation at the same time. It also has has the USB-C charging and data port and a hole for inserting the keychain loop. The Chameleon Ultra dimensions are: 2.4cm x 4cm x 8mm + +![ultra.png](./images/ultra.jpg) + +## The Lite + +The Chameleon Lite comes in a white box with blue printing. This box has the following dimensions: 9.5 cm x 6 cm x 3.5 cm + +![lite-box.jpg](./images/lite-box.jpg) + +The Box contains a foam pad, a USB cable that has a removable end to convert it to USB-C and the device itself. + +![lite-box.-contents.jpg](./images/lite-box-contents.jpg) + +The device itself features 2 buttons labeled with arrows. The device consists of one PCB in a blue plastic housing. This one PCB contains the electronics and the HF antenna as well as the 8 LEDs indicating which slot is currently active, and the USB-C port. The LF antenna is glued onto the back of the PCB and is visible through the housing. The battery is soldered in place and the housing is held together by thin fragile pins which are easy to snap. It is not designed to be disassembled. The keychain loop is also relatively fragile, so be careful. The Chameleon Lites dimensions are: 3.6 cm x 6.1 cm x 0.8 cm + +![lite.jpg](./images/lite.jpg) + +## The Devkit + +Just like the Chameleon Ultra, the Devkit comes in a black box with gold printing. This box has the following dimensions: 12 cm x 8 cm x 3.5 cm + +![devkit-box.jpg](./images/devkit-box.jpg) + +Again, just like the lite, the box contains a foam pad, a USB cable that has a removable end to convert it to USB-C and the device itself. + +![devkit-box-contents.jpg](./images/devkit-box-contents.jpg) + +The device itself features 2 buttons labeled `A` and `B`. The device is made of only one PCB without a case. At the bottom of this PCB both the HF and LF coils are found. Because it is a Devkit, this Chameleon has its SWD (**S**ingle **W**ire **D**ebug) port and some testpoints exposed. (In the photos below, a pinheader is already soldered into the SWD port, this is not the case from factory) The Chameleon Devkit dimensions are: 5.3 cm x 8.5 cm x 1.1 cm (including rubber feet, battery and buttons. PCB thickness: 0,16 cm) + +![devkit.jpg](./images/devkit.jpg) + +## What is the difference between the Lite and the Ultra/DevKit? + +The Chameleon Ultra as well as the Devkit contain a second chip called [MFRC522 ](https://www.nxp.com/docs/en/data-sheet/MFRC522.pdf). This chip allows the Chameleon to read and write to HF 14a tags. The Chameleon Lite does not contain this chip and therefore cannot read and write HF tags, it can only simulate some. The Chameleon Lite also swaps the big LIPO (**LI**thium **PO**lymer) battery with a smaller buttoncell. The Devkit is a Chameleon Ultra on a bigger PCB and with a bigger battery and some component differences such as a mechanical relay but which should not make any practical difference. + +# \ No newline at end of file diff --git a/images/Makefile b/images/Makefile new file mode 100644 index 0000000..814efe7 --- /dev/null +++ b/images/Makefile @@ -0,0 +1,5 @@ +all: + pdflatex --shell-escape protocol-packet.tex + +clean: + rm *.aux *.log *.pdf diff --git a/images/boxnets.zip b/images/boxnets.zip new file mode 100644 index 0000000..3625721 Binary files /dev/null and b/images/boxnets.zip differ diff --git a/images/cli_darkside.png b/images/cli_darkside.png new file mode 100644 index 0000000..8f2ad26 Binary files /dev/null and b/images/cli_darkside.png differ diff --git a/images/cli_mfkey32v2.png b/images/cli_mfkey32v2.png new file mode 100644 index 0000000..898b229 Binary files /dev/null and b/images/cli_mfkey32v2.png differ diff --git a/images/cli_nested.png b/images/cli_nested.png new file mode 100644 index 0000000..564dae8 Binary files /dev/null and b/images/cli_nested.png differ diff --git a/images/cli_staticnested.jpg b/images/cli_staticnested.jpg new file mode 100644 index 0000000..05272b4 Binary files /dev/null and b/images/cli_staticnested.jpg differ diff --git a/images/cugui-devicesettings1.png b/images/cugui-devicesettings1.png new file mode 100644 index 0000000..26d9311 Binary files /dev/null and b/images/cugui-devicesettings1.png differ diff --git a/images/cugui-devicesettings2.png b/images/cugui-devicesettings2.png new file mode 100644 index 0000000..8e70958 Binary files /dev/null and b/images/cugui-devicesettings2.png differ diff --git a/images/cugui-editcard-HF.png b/images/cugui-editcard-HF.png new file mode 100644 index 0000000..efa4445 Binary files /dev/null and b/images/cugui-editcard-HF.png differ diff --git a/images/cugui-editcard-LF.png b/images/cugui-editcard-LF.png new file mode 100644 index 0000000..a532656 Binary files /dev/null and b/images/cugui-editcard-LF.png differ diff --git a/images/cugui-homepage.png b/images/cugui-homepage.png new file mode 100644 index 0000000..bb9fdcf Binary files /dev/null and b/images/cugui-homepage.png differ diff --git a/images/cugui-savedcardinfo.png b/images/cugui-savedcardinfo.png new file mode 100644 index 0000000..d18324d Binary files /dev/null and b/images/cugui-savedcardinfo.png differ diff --git a/images/cugui-savedcards.png b/images/cugui-savedcards.png new file mode 100644 index 0000000..1910fc3 Binary files /dev/null and b/images/cugui-savedcards.png differ diff --git a/images/cugui-searchdialog.png b/images/cugui-searchdialog.png new file mode 100644 index 0000000..7338956 Binary files /dev/null and b/images/cugui-searchdialog.png differ diff --git a/images/cugui-settings.png b/images/cugui-settings.png new file mode 100644 index 0000000..8686247 Binary files /dev/null and b/images/cugui-settings.png differ diff --git a/images/cugui-slotmanager.png b/images/cugui-slotmanager.png new file mode 100644 index 0000000..a98cce5 Binary files /dev/null and b/images/cugui-slotmanager.png differ diff --git a/images/cugui-slotsettings1.png b/images/cugui-slotsettings1.png new file mode 100644 index 0000000..3c726f4 Binary files /dev/null and b/images/cugui-slotsettings1.png differ diff --git a/images/cugui-slotsettings2.png b/images/cugui-slotsettings2.png new file mode 100644 index 0000000..7141e6c Binary files /dev/null and b/images/cugui-slotsettings2.png differ diff --git a/images/devkit-box-contents.jpg b/images/devkit-box-contents.jpg new file mode 100644 index 0000000..7968bf8 Binary files /dev/null and b/images/devkit-box-contents.jpg differ diff --git a/images/devkit-box.jpg b/images/devkit-box.jpg new file mode 100644 index 0000000..2d46734 Binary files /dev/null and b/images/devkit-box.jpg differ diff --git a/images/devkit-boxart.svg b/images/devkit-boxart.svg new file mode 100644 index 0000000..34de0d0 --- /dev/null +++ b/images/devkit-boxart.svg @@ -0,0 +1,42 @@ + + + + diff --git a/images/devkit.jpg b/images/devkit.jpg new file mode 100644 index 0000000..a824d62 Binary files /dev/null and b/images/devkit.jpg differ diff --git a/images/devtool1.jpg b/images/devtool1.jpg new file mode 100644 index 0000000..982962e Binary files /dev/null and b/images/devtool1.jpg differ diff --git a/images/devtool2.jpg b/images/devtool2.jpg new file mode 100644 index 0000000..b6f0b54 Binary files /dev/null and b/images/devtool2.jpg differ diff --git a/images/devtool3.jpg b/images/devtool3.jpg new file mode 100644 index 0000000..b9922b8 Binary files /dev/null and b/images/devtool3.jpg differ diff --git a/images/fdt_chameleon_tiny.png b/images/fdt_chameleon_tiny.png new file mode 100644 index 0000000..810e89d Binary files /dev/null and b/images/fdt_chameleon_tiny.png differ diff --git a/images/fdt_chameleon_ultra.png b/images/fdt_chameleon_ultra.png new file mode 100644 index 0000000..68ab21c Binary files /dev/null and b/images/fdt_chameleon_ultra.png differ diff --git a/images/fdt_flipper_zero.png b/images/fdt_flipper_zero.png new file mode 100644 index 0000000..befd315 Binary files /dev/null and b/images/fdt_flipper_zero.png differ diff --git a/images/fdt_pm3_rdv401.png b/images/fdt_pm3_rdv401.png new file mode 100644 index 0000000..5f01af5 Binary files /dev/null and b/images/fdt_pm3_rdv401.png differ diff --git a/images/fdt_redmi_k30.png b/images/fdt_redmi_k30.png new file mode 100644 index 0000000..fcfe268 Binary files /dev/null and b/images/fdt_redmi_k30.png differ diff --git a/images/fdt_standard_s50.png b/images/fdt_standard_s50.png new file mode 100644 index 0000000..c420094 Binary files /dev/null and b/images/fdt_standard_s50.png differ diff --git a/images/fdt_touchngo_s70_cpu.png b/images/fdt_touchngo_s70_cpu.png new file mode 100644 index 0000000..90c5d19 Binary files /dev/null and b/images/fdt_touchngo_s70_cpu.png differ diff --git a/images/hardware_overview.png b/images/hardware_overview.png new file mode 100644 index 0000000..53dda23 Binary files /dev/null and b/images/hardware_overview.png differ diff --git a/images/lite-box-contents.jpg b/images/lite-box-contents.jpg new file mode 100644 index 0000000..e875475 Binary files /dev/null and b/images/lite-box-contents.jpg differ diff --git a/images/lite-box.jpg b/images/lite-box.jpg new file mode 100644 index 0000000..c0442c1 Binary files /dev/null and b/images/lite-box.jpg differ diff --git a/images/lite-boxart.svg b/images/lite-boxart.svg new file mode 100644 index 0000000..5eab557 --- /dev/null +++ b/images/lite-boxart.svg @@ -0,0 +1,42 @@ + + + + diff --git a/images/lite.jpg b/images/lite.jpg new file mode 100644 index 0000000..00fe3a0 Binary files /dev/null and b/images/lite.jpg differ diff --git a/images/measured-ask.png b/images/measured-ask.png new file mode 100644 index 0000000..e14b7b4 Binary files /dev/null and b/images/measured-ask.png differ diff --git a/images/measured-fsk.png b/images/measured-fsk.png new file mode 100644 index 0000000..60b7edc Binary files /dev/null and b/images/measured-fsk.png differ diff --git a/images/measured-psk.png b/images/measured-psk.png new file mode 100644 index 0000000..0e86017 Binary files /dev/null and b/images/measured-psk.png differ diff --git a/images/protocol-packet.png b/images/protocol-packet.png new file mode 100644 index 0000000..2092f14 Binary files /dev/null and b/images/protocol-packet.png differ diff --git a/images/protocol-packet.tex b/images/protocol-packet.tex new file mode 100644 index 0000000..82449ac --- /dev/null +++ b/images/protocol-packet.tex @@ -0,0 +1,24 @@ +\documentclass[border=10pt,png]{standalone} +\usepackage{bytefield} +\usepackage{xcolor} + +\begin{document} + + \definecolor{lightcyan}{rgb}{0.85,1,1} + \definecolor{lightgreen}{rgb}{0.85,1,0.85} + \definecolor{lightred}{rgb}{1,0.85,0.85} + \begin{bytefield}[bitwidth=1.1em]{32} + \bitbox{8}[bgcolor=lightcyan]{SOF} & + \bitbox{8}[bgcolor=lightcyan]{LRC1} & + \bitbox{16}[bgcolor=lightgreen]{CMD} \\ + \bitbox{16}[bgcolor=lightgreen]{STATUS} & + \bitbox{16}[bgcolor=lightgreen]{LEN} \\ + \bitbox{8}[bgcolor=lightgreen]{LRC2} & + \bitbox[tlr]{24}[bgcolor=lightred]{} \\ + \wordbox[lr]{1}[bgcolor=lightred]{DATA} \\ + \wordbox[lr]{1}[bgcolor=lightred]{$\cdots$} \\ + \bitbox[blr]{24}[bgcolor=lightred]{} & + \bitbox{8}[bgcolor=lightred]{LRC3} + \end{bytefield} + +\end{document} diff --git a/images/ultra-box-contents.jpg b/images/ultra-box-contents.jpg new file mode 100644 index 0000000..b37befc Binary files /dev/null and b/images/ultra-box-contents.jpg differ diff --git a/images/ultra-box.jpg b/images/ultra-box.jpg new file mode 100644 index 0000000..2ba9e2a Binary files /dev/null and b/images/ultra-box.jpg differ diff --git a/images/ultra-boxart.svg b/images/ultra-boxart.svg new file mode 100644 index 0000000..c407799 --- /dev/null +++ b/images/ultra-boxart.svg @@ -0,0 +1,42 @@ + + + + diff --git a/images/ultra-logo.png b/images/ultra-logo.png new file mode 100644 index 0000000..dc857b3 Binary files /dev/null and b/images/ultra-logo.png differ diff --git a/images/ultra-overview.png b/images/ultra-overview.png new file mode 100644 index 0000000..a9a187b Binary files /dev/null and b/images/ultra-overview.png differ diff --git a/images/ultra.jpg b/images/ultra.jpg new file mode 100644 index 0000000..3ac878c Binary files /dev/null and b/images/ultra.jpg differ diff --git a/images/yaxilalei.jpg b/images/yaxilalei.jpg new file mode 100644 index 0000000..66b2a7d Binary files /dev/null and b/images/yaxilalei.jpg differ diff --git a/modding.md b/modding.md new file mode 100644 index 0000000..b2c4072 --- /dev/null +++ b/modding.md @@ -0,0 +1,4 @@ +# Third party moddings + +* [ChameleonUltra Keyring](https://www.printables.com/model/552739-chameleonultra-keyring), an extended frame for ChameleonUltra with a sturdy keyring loop. +* [ChameleonUltra Wristband](https://www.thingiverse.com/thing:6153027), allows the user to wear the ChameleonUltra as a wristband. diff --git a/mtoolsble.md b/mtoolsble.md new file mode 100644 index 0000000..6586f9d --- /dev/null +++ b/mtoolsble.md @@ -0,0 +1,50 @@ +# MTools BLE Introduction +MTools BLE supports managing the ChamleonUltra, ChameleonLite and DevKits via BLE connections. +## Downlaod Link +- [MTools BLE on iOS](https://apps.apple.com/app/mtools-ble-rfid-reader/id1531345398) +- [MTools BLE on Google Play](https://play.google.com/store/apps/details?id=com.mtoolstec.mtoolsLite) + +## How to connect with Bluetooth in MTools BLE +1. Click **A** or **B** button to power on. +2. Click **Bluetooth List** icon in App to search devices. +3. Click **Connect** button on the right to connect. + +#### Notice for Bluetooth Connection +1. Grant the Bluetooth permission of App on iOS. +2. Allow Location permission to scan Bluetooth devices on Android. + +## Features for ChameleonUltra +### Slot Manager +1. Fetch all slot status. +2. Enable or disable Slots. +3. Change LF and HF Slot name. +4. Set LF and HF Tag Type. +5. Delete and reset all slots. + +### Reader +1. Fast read LF and HF Tag. +2. Simulate Mifare Classic Tag with UID, SAK, ATQA and empty dump. +3. Simulate Mifare Ultralight Tag with UID, SAK, ATQA and empty dump. +4. Simulate EM410X LF tag or manually set the ID then simulate. + +### Mifare Classic Dump +1. eRead full dump from current active slot to App. +2. Upload full dump to current active slot and simulate. +3. Read Mifare Mini, 1K, 2K, 4K dump from tag with known keys. +4. Write Gen1A, Gen2, Gen3, Gen4 dump to tag with known keys. +5. Format common and magic Mifare Classic tags. +6. Modify block data and save to new dump file. + +### Mifare Ultralight Dump +1. eRead full dump from current active slot to App. +2. Upload full dump to current active slot and simulate. +3. Read Mifare Ultralight dump from tag. +4. Write Mifare Ultralight dump to tag. + +### Settings +1. Set the Animation of LEDs. +2. Set press and long press button of A and B. +3. Set the **Mifare Classic Emulation** of current slot. +4. Set the **Mifare Ultralight Emulation** of current slot. +5. DFU Tool for updating firmware. +6. Reset Chameleon Device. \ No newline at end of file diff --git a/protocol.md b/protocol.md new file mode 100644 index 0000000..2994173 --- /dev/null +++ b/protocol.md @@ -0,0 +1,481 @@ +# Protocol description + +## Versioning + +Global firmware+CLI versions are following the [semantic versioning](https://semver.org/) logic mostly regarding the protocol version, so third party clients (GUIs, mobile apps, SDKs) can rely on firmware version to know their level of compatibility. + +Given a version number MAJOR.MINOR.PATCH, we will increment the: +* MAJOR version when we are breaking the existing protocol format +* MINOR version when we are extending the protocol format in a backward compatible manner (new commands,...) +* PATCH version when we are releasing bugfixes not affecting the protocol description + +Besides compatibility with a given firmware version, third party clients may choose to offer to the users the possibility to follow a stable release channel (installing only tagged releases) or the development channel (installing latest commits). + +For the stable channel, a client compatible with versions X.y.z can accept any version > X.y'.z' but should refuse to work with a version X'>X. + +For the development channel, a client compatible with versions X.y.z can accept any latest commit unless a tag X'.0.0 with X'>X is present in the repo, indicating that the corresponding commit and all the commits above are incompatible with the client version. There is still a non negligible risk that breaking changes are pushed while forgetting about putting a new tag, or artefacts being built before the tag being pushed. Here be dragons... It's always a good practice for the client to validate whatever data is transmitted by the firmware, and fail gracefully in case of hiccups. + +Cf [GET_APP_VERSION](#1000-get_app_version) and [GET_GIT_VERSION](#1017-get_git_version). + +When `GET_GIT_VERSION` returns only a tag and no commit hash info (on a release tag), one can query the corresponding hash with the GitHub API, e.g. +``` +"4747d3884d21e0df8549e3029a920ea390e0b00a" +``` +## Frame format + +The communication between the firmware and the client is made of frames structured as follows: + +![](images/protocol-packet.png) + +- **SOF**: `1 byte`, "**S**tart-**O**f-**F**rame byte" represents the start of a packet, and must be equal to `0x11`. +- **LRC1**: `1 byte`, LRC over `SOF` byte, therefore must be equal to `0xEF`. +- **CMD**: `2 bytes`, each command have been assigned a unique number (e.g. `DATA_CMD_SET_SLOT_TAG_NICK` = `1007`). +- **STATUS**: `2 bytes`. + - From client to firmware, the status is always `0x0000`. + - From firmware to client, the status is the result of the command. +- **LEN**: `2 bytes`, length of the `DATA` field, maximum is `512`. +- **LRC2**: `1 byte`, LRC over `CMD|STATUS|LEN` bytes. +- **DATA**: `LEN bytes`, data to be sent or received, maximum is `512 bytes`. This payload depends on the exact command or response to command being used. See [Packet payloads](#packet-payloads) below. +- **LRC3**: `1 byte`, LRC over `DATA` bytes. + +Notes: +* The same frame format is used for commands and for responses. +* All values are **unsigned** values, and if more than one byte, in **network byte order**, aka [Big Endian](https://en.wikipedia.org/wiki/Endianness) byte order. +* The total length of the packet is `LEN + 10` bytes, therefore it is between `10` and `522` bytes. +* The LRC ([**L**ongitudinal **R**edundancy **C**heck](https://en.wikipedia.org/wiki/Longitudinal_redundancy_check)) is the 8-bit two's-complement value of the sum of all bytes modulo $2^8$. +* LRC2 and LRC3 can be computed equally as covering either the frame from its first byte or from the byte following the previous LRC, because previous LRC nullifies previous bytes LRC computation. +E.g. LRC3(DATA) == LRC3(whole frame) + +## Data payloads + +Each command and response have their own payload formats. + +Standard response status is `STATUS_SUCCESS` for general commands, `STATUS_HF_TAG_OK` for HF commands and `STATUS_LF_TAG_OK` for LF commands. +See [Guidelines](#new-data-payloads-guidelines-for-developers) for more info. + +Beware, slots in protocol count from 0 to 7 (and from 1 to 8 in the CLI...). + +In the following list, "CLI" refers to one typical CLI command using the described protocol command. But it's not a 1:1 match, there can be other protocol commands used by the CLI command and there can be other CLI commands using the same protocol command... + +### 1000: GET_APP_VERSION +* Command: no data +* Response: 2 bytes: `version_major|version_minor` +* CLI: cf `hw version` +### 1001: CHANGE_DEVICE_MODE +* Command: 1 byte. `0x00`=emulator mode, `0x01`=reader mode +* Response: no data +* CLI: cf `hw mode` +### 1002: GET_DEVICE_MODE +* Command: no data +* Response: data: 1 byte. `0x00`=emulator mode, `0x01`=reader mode +* CLI: cf `hw mode` +### 1003: SET_ACTIVE_SLOT +* Command: 1 byte. `slot_number` between 0 and 7 +* Response: no data +* CLI: cf `hw slot change` +### 1004: SET_SLOT_TAG_TYPE +* Command: 3 bytes. `slot_number|tag_type[2]` with `slot_number` between 0 and 7 and `tag_type` according to `tag_specific_type_t` enum, U16 in Network byte order. +* Response: no data +* CLI: cf `hw slot type` +### 1005: SET_SLOT_DATA_DEFAULT +* Command: 3 bytes. `slot_number|tag_type[2]` with `slot_number` between 0 and 7 and `tag_type` U16 according to `tag_specific_type_t` enum, U16 in Network byte order. +* Response: no data +* CLI: cf `hw slot init` +### 1006: SET_SLOT_ENABLE +* Command: 3 bytes. `slot_number|sense_type|enable` with `slot_number` between 0 and 7, `sense_type` according to `tag_sense_type_t` enum and `enable` = `0x01` to enable, `0x00` to disable +* Response: no data +* CLI: cf `hw slot enable`/`hw slot disable` +### 1007: SET_SLOT_TAG_NICK +* Command: 2+N bytes. `slot_number|sense_type|name[N]` with `slot_number` between 0 and 7, `sense_type` according to `tag_sense_type_t` enum and `name` a UTF-8 encoded string of max 32 bytes, no null terminator. +* Response: no data +* CLI: cf `hw slot nick` +### 1008: GET_SLOT_TAG_NICK +* Command: 2 bytes. `slot_number|sense_type` with `slot_number` between 0 and 7 and `sense_type` according to `tag_sense_type_t` enum. +* Response: a UTF-8 encoded string of max 32 bytes, no null terminator. If no nick name has been recorded in Flash, response status is `STATUS_FLASH_READ_FAIL`. +* CLI: cf `hw slot nick` +### 1009: SLOT_DATA_CONFIG_SAVE +* Command: no data +* Response: no data +* CLI: cf `hw slot store` +### 1010: ENTER_BOOTLOADER +* Command: no data +* Response: this special command does not return and will interrupt the communication link while rebooting in bootloader mode, needed for DFU. +* CLI: cf `hw dfu` +### 1011: GET_DEVICE_CHIP_ID +* Command: no data +* Response: 8 bytes. nRF `DEVICEID[8]` U64 in Network byte order. +* CLI: cf `hw chipid` +### 1012: GET_DEVICE_ADDRESS +* Command: no data +* Response: 6 bytes. nRF `DEVICEADDR[6]` U48 in Network byte order. First 2 MSBits forced to `0b11` to match BLE static address. +* CLI: cf `hw address` +### 1013: SAVE_SETTINGS +* Command: no data +* Response: no data +* CLI: cf `hw settings store` +### 1014: RESET_SETTINGS +* Command: no data +* Response: no data +* CLI: cf `hw settings reset` +### 1015: SET_ANIMATION_MODE +* Command: 1 byte, according to `settings_animation_mode_t` enum. +* Response: no data +* CLI: cf `hw settings animation` +### 1016: GET_ANIMATION_MODE +* Command: no data +* Response: 1 byte, according to `settings_animation_mode_t` enum. +* CLI: cf `hw settings animation` +### 1017: GET_GIT_VERSION +* Command: no data +* Response: n bytes, a UTF-8 encoded string, no null terminator. +* CLI: cf `hw version` + +Notes: the returned string is the output of `git describe --abbrev=7 --dirty --always --tags --match "v*.*"` so, depending on the status of the repo it can be +* a short tag, e.g. `v2.0.0` if the firmware is built from the tagged commit +* a longer tag indicating how far it is from the latest tag and 7 nibbles of its commit hash, prepended with `g`, e.g. 5 commits away from v2.0.0: `v2.0.0-5-g617d6d0` +* a long tag finishing with `-dirty` if the local repo contains changes not yet committed, e.g. `v2.0.0-5-g617d6d0-dirty` +### 1018: GET_ACTIVE_SLOT +* Command: no data +* Response: 1 byte +* CLI: cf `hw slot list` +### 1019: GET_SLOT_INFO +* Command: no data +* Response: 32 bytes, 8 tuples `hf_tag_type[2]|lf_tag_type[2]` according to `tag_specific_type_t` enum, for slots from 0 to 7, U16 in Network byte order. +* CLI: cf `hw slot list` +### 1020: WIPE_FDS +* Command: no data +* Response: no data. Status is `STATUS_SUCCESS` or `STATUS_FLASH_WRITE_FAIL`. The device will reboot shortly after this command. +* CLI: cf `hw factory_reset` +### 1021: DELETE_SLOT_TAG_NICK +* Command: 2 bytes. `slot_number|sense_type` with `slot_number` between 0 and 7 and `sense_type` according to `tag_sense_type_t` enum. +* Response: no data +* CLI: cf `hw slot nick` +### 1023: GET_ENABLED_SLOTS +* Command: no data +* Response: 16 bytes, 8*2 bool = `0x00` or `0x01`, 2 bytes for each slot from 0 to 7, as `enabled_hf|enabled_lf` +* CLI: cf `hw slot list` +### 1024: DELETE_SLOT_SENSE_TYPE +* Command: 2 bytes. `slot_number|sense_type` with `slot_number` between 0 and 7 and `sense_type` according to `tag_sense_type_t` enum. +* Response: no data +* CLI: cf `hw slot delete` +### 1025: GET_BATTERY_INFO +* Command: no data +* Response: 3 bytes, `voltage[2]|percentage`. Voltage: U16 in Network byte order. +* CLI: cf `hw battery` + +Notes: wait about 5 seconds after wake-up, before querying the battery status, else the device won't be able to give a proper measure and will return zeroes. +### 1026: GET_BUTTON_PRESS_CONFIG +* Command: 1 byte. Char `A` or `B` (`a`/`b` tolerated too) +* Response: 1 byte, `button_function` according to `settings_button_function_t` enum. +* CLI: cf `hw settings btnpress` +### 1027: SET_BUTTON_PRESS_CONFIG +* Command: 2 bytes. `button|button_function` with `button` char `A` or `B` (`a`/`b` tolerated too) and `button_function` according to `settings_button_function_t` enum. +* Response: no data +* CLI: cf `hw settings btnpress` +### 1028: GET_LONG_BUTTON_PRESS_CONFIG +* Command: 1 byte. Char `A` or `B` (`a`/`b` tolerated too) +* Response: 1 byte, `button_function` according to `settings_button_function_t` enum. +* CLI: cf `hw settings btnpress` +### 1029: SET_LONG_BUTTON_PRESS_CONFIG +* Command: 2 bytes. `button|button_function` with `button` char `A` or `B` (`a`/`b` tolerated too) and `button_function` according to `settings_button_function_t` enum. +* Response: no data +* CLI: cf `hw settings btnpress` +### 1030: SET_BLE_PAIRING_KEY +* Command: 6 bytes. 6 ASCII-encoded digits. +* Response: no data +* CLI: cf `hw settings blekey` +### 1031: GET_BLE_PAIRING_KEY +* Command: no data +* Response: 6 bytes. 6 ASCII-encoded digits. +* CLI: cf `hw settings blekey` +### 1032: DELETE_ALL_BLE_BONDS +* Command: no data +* Response: no data +* CLI: cf `hw settings bleclearbonds` +### 1033: GET_DEVICE_MODEL +* Command: no data +* Response: 1 byte. `hw_version` aka `NRF_DFU_HW_VERSION` according to `chameleon_device_type_t` enum (0=Ultra, 1=Lite) +* CLI: cf `hw version` +### 1034: GET_DEVICE_SETTINGS +* Command: no data +* Response: 14 bytes + * `settings_current_version` = `5` + * `animation_mode`, cf [GET_ANIMATION_MODE](#1016-get_animation_mode) + * `btn_press_A`, cf [GET_BUTTON_PRESS_CONFIG](#1026-get_button_press_config) + * `btn_press_B`, cf [GET_BUTTON_PRESS_CONFIG](#1026-get_button_press_config) + * `btn_long_press_A`, cf [GET_LONG_BUTTON_PRESS_CONFIG](#1028-get_long_button_press_config) + * `btn_long_press_B`, cf [GET_LONG_BUTTON_PRESS_CONFIG](#1028-get_long_button_press_config) + * `ble_pairing_enable`, cf [GET_BLE_PAIRING_ENABLE](#1036-get_ble_pairing_enable) + * `ble_pairing_key[6]`, cf [GET_BLE_PAIRING_KEY](#1031-get_ble_pairing_key) +* CLI: unused +### 1035: GET_DEVICE_CAPABILITIES +* Command: no data +* Response: 2*n bytes, a list of supported commands IDs. +* CLI: used internally on connect +### 1036: GET_BLE_PAIRING_ENABLE +* Command: no data +* Response: 1 byte, bool = `0x00` or `0x01` +* CLI: cf `hw settings blepair` +### 1037: SET_BLE_PAIRING_ENABLE +* Command: 1 byte, bool = `0x00` or `0x01` +* Response: no data +* CLI: cf `hw settings blepair` +### 2000: HF14A_SCAN +* Command: no data +* Response: N bytes: `tag1_data|tag2_data|...` with each tag: `uidlen|uid[uidlen]|atqa[2]|sak|atslen|ats[atslen]`. UID, ATQA, SAK and ATS as bytes. +* CLI: cf `hf 14a scan` + +Notes: +* remind that if no tag is present, status will be `STATUS_HF_TAG_NO` and Response empty. +* at the moment, the firmware supports only one tag, but get your client ready for more! +* `atslen` must not be confused with `ats[0]`==`TL`. So `atslen|ats` = `00` means no ATS while `0100` would be an empty ATS. +### 2001: MF1_DETECT_SUPPORT +* Command: no data +* Response: 1 byte, bool = `0x00` or `0x01` +* CLI: cf `hf 14a info` +### 2002: MF1_DETECT_PRNG +* Command: no data +* Response: 1 byte, according to `mf1_nested_type_t` enum +* CLI: cf `hf 14a info` +### 2003: MF1_STATIC_NESTED_ACQUIRE +* Command: 10 bytes: `type_known|block_known|key_known[6]|type_target|block_target`. Key as 6 bytes. +* Response: 4+N*8 bytes: `uid[4]` followed by N tuples of `nt[4]|nt_enc[4]`. All values as U32. +* CLI: cf `hf mf nested` on static nonce tag +### 2004: MF1_DARKSIDE_ACQUIRE +* Command: 4 bytes: `type_target|block_target|first_recover|sync_max`. Type=0x60 for key A, 0x61 for key B. +* Response: 1 byte if Darkside failed, according to `mf1_darkside_status_t` enum, + else 33 bytes `darkside_status|uid[4]|nt1[4]|par[8]|ks1[8]|nr[4]|ar[4]` + * `darkside_status` + * `uid[4]` U32 (format expected by `darkside` tool) + * `nt1[4]` U32 + * `par[8]` U64 + * `ks1[8]` U64 + * `nr[4]` U32 + * `ar[4]` U32 +* CLI: cf `hf mf darkside` +### 2005: MF1_DETECT_NT_DIST +* Command: 8 bytes: `type_known|block_known|key_known[6]`. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B. +* Response: 8 bytes: `uid[4]|dist[4]` + * `uid[4]` U32 (format expected by `nested` tool) + * `dist[4]` U32 +* CLI: cf `hf mf nested` +### 2006: MF1_NESTED_ACQUIRE +* Command: 10 bytes: `type_known|block_known|key_known[6]|type_target|block_target`. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B. +* Response: N*9 bytes: N tuples of `nt[4]|nt_enc[4]|par` + * `nt[4]` U32 + * `nt_enc[4]` U32 + * `par` +* CLI: cf `hf mf nested` +### 2007: MF1_AUTH_ONE_KEY_BLOCK +* Command: 8 bytes: `type|block|key[6]`. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B. +* Response: no data +* Status will be `STATUS_HF_TAG_OK` if auth succeeded, else `STATUS_MF_ERR_AUTH` +* CLI: cf `hf mf nested` +### 2008: MF1_READ_ONE_BLOCK +* Command: 8 bytes: `type|block|key[6]`. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B. +* Response: 16 bytes: `block_data[16]` +* CLI: cf `hf mf rdbl` +### 2009: MF1_WRITE_ONE_BLOCK +* Command: 24 bytes: `type|block|key[6]|block_data[16]`. Key as 6 bytes. Type=0x60 for key A, 0x61 for key B. +* Response: no data +* CLI: cf `hf mf wrbl` +### 2010: HF14A_RAW +* Command: : 5+N bytes: `options|resp_timeout_ms[2]|bitlen[2]` followed by data to be transmitted, with `options` a 1-byte BigEndian bitfield, so starting from MSB: + * `activate_rf_field`:1 + * `wait_response`:1 + * `append_crc`:1 + * `auto_select`:1 + * `keep_rf_field`:1 + * `check_response_crc`:1 + * `reserved`:2 +* Response: data sent by the card +* CLI: cf `hf 14a raw` +### 2011: MF1_MANIPULATE_VALUE_BLOCK +* Command: 21 bytes: `src_type|src_block|src_key[6]|operator|operand[4]|dst_type|dst_block|dst_key[6]`. Key as 6 bytes. Type=`0x60` for key A, `0x61` for key B. Operator=`0xC0` for decrement, `0xC1` for increment, `0xC2` for restore. Operand as I32 in Network byte order. +* Response: no data +* CLI: cf `hf mf value` +### 2012: MF1_CHECK_KEYS_OF_SECTORS +* Command: 10+N*6 bytes: `mask[10]|keys[N][6]` (1<=N<=83) + * `mask`: 40 sectors, 2 bits/sector, MSB: `0A|0B|1A|1B|...|39A|39B`. `0b1` represent to skip checking the key. +* Response: 490 bytes: `found[10]|sectorKey[40][2][6]`. + * `found`: 40 sectors, 2 bits/sector, MSB: `0A|0B|1A|1B|...|39A|39B`. `0b1` represent the key is found. + * `sectorKey`: 40 sectors, 2 keys/sector, 6 bytes/key: `key0A[6]|key0B[6]|key1A[6]|key1B[6]|...|key39A[6]|key39B[6]` +* CLI: cf `hf mf fchk` +### 3000: EM410X_SCAN +* Command: no data +* Response: 5 bytes. `id[5]`. ID as 5 bytes. +* CLI: cf `lf em 410x read` +### 3001: EM410X_WRITE_TO_T55XX +* Command: 9+N*4 bytes: `id[5]|new_key[4]|old_key1[4]|old_key2[4]|...` (N>=1). . ID as 5 bytes. Keys as 4 bytes. +* Response: no data +* CLI: cf `lf em 410x write` +### 4000: MF1_WRITE_EMU_BLOCK_DATA +* Command: 1+N*16 bytes: `block_start|block_data1[16]|block_data2[16]|...` (1<=N<=31) +* Response: no data +* CLI: cf `hf mf eload` +### 4001: HF14A_SET_ANTI_COLL_DATA +* Command: N bytes: `uidlen|uid[uidlen]|atqa[2]|sak|atslen|ats[atslen]`. UID, ATQA, SAK and ATS as bytes. +* Response: no data +* CLI: cf `hf mf econfig`/`hf mfu econfig` +### 4004: MF1_SET_DETECTION_ENABLE +* Command: 1 byte, bool = `0x00` or `0x01` +* Response: no data +* CLI: cf `hf mf econfig` +### 4005: MF1_GET_DETECTION_COUNT +* Command: no data +* Response: 4 bytes, `count[4]`, U32 in Network byte order. +* CLI: cf `hf mf elog` +### 4006: MF1_GET_DETECTION_LOG +* Command: 4 bytes, `index`, U32 in Network byte order. +* Response: N*18 bytes. 0<=N<=28 + * `block` + * `...|is_nested|is_key_b` 1-byte bitfield, starting from LSB + * `uid[4]` ? + * `nt[4]` ? + * `nr[4]` ? + * `ar[4]` ? +* CLI: cf `hf mf elog` +### 4007: MF1_GET_DETECTION_ENABLE +* Command: no data +* Response: 1 byte, bool = `0x00` or `0x01` +* CLI: cf `hw slot list` +### 4008: MF1_READ_EMU_BLOCK_DATA +* Command: 2 bytes: `block_start|block_count` with 1<=`block_count` <=32 +* Response: `block_count`*16 bytes +* CLI: cf `hf mf eread` +### 4009: MF1_GET_EMULATOR_CONFIG +* Command: no data +* Response: 5 bytes + * `detection`, cf [MF1_GET_DETECTION_ENABLE](#4007-mf1_get_detection_enable) + * `gen1a_mode`, cf [MF1_GET_GEN1A_MODE](#4010-mf1_get_gen1a_mode) + * `gen2_mode`, cf [MF1_GET_GEN2_MODE](#4012-mf1_get_gen2_mode) + * `block_anti_coll_mode`, cf [MF1_GET_BLOCK_ANTI_COLL_MODE](#4014-mf1_get_block_anti_coll_mode) + * `write_mode`, cf [MF1_GET_WRITE_MODE](#4016-mf1_get_write_mode) +* CLI: cf `hf mf econfig` +### 4010: MF1_GET_GEN1A_MODE +* Command: no data +* Response: 1 byte, bool = `0x00` or `0x01` +* CLI: unused +### 4011: MF1_SET_GEN1A_MODE +* Command: 1 byte, bool = `0x00` or `0x01` +* Response: no data +* CLI: cf `hf mf econfig` +### 4012: MF1_GET_GEN2_MODE +* Command: no data +* Response: 1 byte, bool = `0x00` or `0x01` +* CLI: unused +### 4013: MF1_SET_GEN2_MODE +* Command: 1 byte, bool = `0x00` or `0x01` +* Response: no data +* CLI: cf `hf mf econfig` +### 4014: MF1_GET_BLOCK_ANTI_COLL_MODE +* Command: no data +* Response: 1 byte, bool = `0x00` or `0x01` +* CLI: unused +### 4015: MF1_SET_BLOCK_ANTI_COLL_MODE +* Command: 1 byte, bool = `0x00` or `0x01` +* Response: no data +* CLI: cf `hf mf econfig` +### 4016: MF1_GET_WRITE_MODE +* Command: no data +* Response: 1 byte, according to `nfc_tag_mf1_write_mode_t` aka `MifareClassicWriteMode` enum +* CLI: unused +### 4017: MF1_SET_WRITE_MODE +* Command: 1 byte, according to `nfc_tag_mf1_write_mode_t` aka `MifareClassicWriteMode` enum +* Response: no data +* CLI: cf `hf mf econfig` +### 4018: HF14A_GET_ANTI_COLL_DATA +* Command: no data +* Response: no data or N bytes: `uidlen|uid[uidlen]|atqa[2]|sak|atslen|ats[atslen]`. UID, ATQA, SAK and ATS as bytes. +* CLI: cf `hw slot list`/`hf mf econfig`/`hf mfu econfig` +### 4019: MF0_NTAG_GET_UID_MAGIC_MODE +* Command: no data +* Response: 1 byte where a non-zero value indicates that UID magic mode is enabled for the current slot. +* CLI: cf `hf mfu econfig` +### 4020: MF0_NTAG_SET_UID_MAGIC_MODE +* Command: 1 byte where a non-zero value indicates that UID magic mode should be enabled for the current slot, otherwise disabled. +* Response: no data +* CLI: cf `hf mfu econfig --enable-uid-magic`/`hf mfu econfig --disable-uid-magic` +### 4021: MF0_NTAG_READ_EMU_PAGE_DATA +* Command: 2 bytes: one for first page index, one for count of pages to be read. +* Response: `4 * n` bytes where `n` is the number if pages to be read +* CLI: cf `hf mfu eview` +### 4022: MF0_NTAG_WRITE_EMU_PAGE_DATA +* Command: 2 + `n * 4` bytes: one for first page index, one for count of pages to be read, `n * 4` for `n` pages data. +* Response: no data +* CLI: unused +### 4023: MF0_NTAG_GET_VERSION_DATA +* Command: no data +* Response: 8 version data bytes. +* CLI: cf `hf mfu econfig` +### 4024: MF0_NTAG_SET_VERSION_DATA +* Command: 8 version data bytes. +* Response: no data +* CLI: cf `hf mfu econfig --set-version ` +### 4025: MF0_NTAG_GET_SIGNATURE_DATA +* Command: no data +* Response: 32 signature data bytes. +* CLI: cf `hf mfu econfig` +### 4026: MF0_NTAG_SET_SIGNATURE_DATA +* Command: 32 signature data bytes. +* Response: no data +* CLI: cf `hf mfu econfig --set-signature ` +### 4027: MF0_NTAG_GET_COUNTER_DATA +* Command: 1 byte for the counter index +* Response: 3 bytes for the counter value (big-endian) + 1 byte for tearing where `0xBD` means tearing flag is not set. +* CLI: cf `hf mfu ercnt` +### 4028: MF0_NTAG_SET_COUNTER_DATA +* Command: 1 byte where the lower 7 bits are the counter index and the top bit indicates whether tearing event flag should be reset + 3 bytes of the counter value (big-endian). +* Response: no data +* CLI: cf `hf mfu ewcnt` +### 4029: MF0_NTAG_RESET_AUTH_CNT +* Command: no data +* Response: 1 byte for the old value of the unsuccessful auth counter. +* CLI: cf `hf mfu econfig --reset-auth-cnt` +### 4030: MF0_NTAG_GET_PAGE_COUNT +* Command: no data +* Response: 1 byte is the number of pages available in the current card slot +* CLI: unused +### 5000: EM410X_SET_EMU_ID +* Command: 5 bytes. `id[5]`. ID as 5 bytes. +* Response: no data +* CLI: cf `lf em 410x econfig` +### 5001: EM410X_GET_EMU_ID +* Command: no data +* Response: 5 bytes. `id[5]`. ID as 5 bytes. +* CLI: cf `lf em 410x econfig` + +## New data payloads: guidelines for developers + +If you need to define new payloads for new commands, try to follow these guidelines. + +### Guideline: Verbose and explicit +Be verbose, explicit and reuse conventions, in order to enhance code maintainability and understandability for the other contributors +### Guideline: Structs +- Define C `struct` for cmd/resp data greater than a single byte, use and abuse of `struct.pack`/`struct.unpack` in Python. So one can understand the payload format at a simple glimpse. Exceptions to `C` struct are when the formats are of variable length (but Python `struct` is still flexible enough to cope with such formats!) +- Avoid hardcoding offsets, use `sizeof()`, `offsetof(struct, field)` in C and `struct.calcsize()` in Python +- For complex bitfield structs, exceptionally you can use ctypes in Python. Beware ctypes.BigEndianStructure bitfield will be parsed in the firmware in the reverse order, from LSB to MSB. +### Guideline: Status +If single byte of data to return, still use a 1-byte `data`, not `status`. Standard response status is `STATUS_SUCCESS` for general commands, `STATUS_HF_TAG_OK` for HF commands and `STATUS_LF_TAG_OK` for LF commands. If the response status is different than those, the response data is empty. Response status are generic and cover things like tag disappearance or tag non-conformities with the ISO standard. If a command needs more specific response status, it is added in the first byte of the data, to avoid cluttering the 1-byte general status enum with command-specific statuses. See e.g. [MF1_DARKSIDE_ACQUIRE](#2004-mf1_darkside_acquire). +### Guideline: unambiguous types +- Use unambiguous types such as `uint16_t`, not `int` or `enum`. Cast explicitly `int` and `enum` to `uint_t` of proper size +- Use Network byte order for 16b and 32b integers + - Macros `U16NTOHS`, `U32NTOHL` must be used on reception of a command payload. + - Macros `U16HTONS`, `U32HTONL` must be used on creation of a response payload. + - In Python, use the modifier `!` with all `struct.pack`/`struct.unpack` +### Guideline: payload parsing in handlers +- Concentrate payload parsing in the handlers, avoid further parsing in their callers. Callers should not care about the protocol. This is true for the firmware and the client. +- In cmd_processor handlers: don't reuse input `length`/`data` parameters for creating the response content +### Guideline: Naming conventions +- Use the exact same command and fields names in firmware and in client, use function names matching the command names for their handlers unless there is a very good reason not to do so. This helps grepping around. Names must start with a letter, not a number, because some languages require it (e.g. `14a_scan` not possible in Python) +- Respect commands order in `m_data_cmd_map`, `data_cmd.h` and `chameleon_cmd.py` definitions +- Even if a command is not yet implemented in firmware or in client but a command number is allocated, add it to `data_cmd.h` and `chameleon_cmd.py` with some `FIXME: to be implemented` comment +### Guideline: Validate status and data +- Validate response status in client before parsing data. +- Validate data before using it. + +## Room for improvement + +* some `num_to_bytes` `bytes_to_num` could use `hton*`, `ntoh*` instead, to make endianess explicit +* some commands are using bitfields (e.g. mf1_get_detection_log (sending directly the flash stored format) and hf14a_raw) while some commands are spreading bits into 0x00/0x01 bytes (e.g. mf1_get_emulator_config) +* describe flash storage formats diff --git a/quickstart.md b/quickstart.md new file mode 100644 index 0000000..6e93a38 --- /dev/null +++ b/quickstart.md @@ -0,0 +1,19 @@ +# Quickstart + +Quickly get up and running with your Chameleon and no technical skill + +1. Download any of those applications. Note that in spite of what their name may suggest, all GUIs support both the Ultra and the Lite. + + - [ChameleonUltraGUI on Google Play](https://play.google.com/store/apps/details?id=io.chameleon.ultra) / [APK](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/apk.zip) + - [ChameleonUltraGUI on iOS](https://apps.apple.com/dk/app/chameleon-ultra-gui/id6462919364) + - [ChameleonUltraGUI on Windows](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/windows-installer.zip) ([or without installer](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/windows.zip)) + - [ChameleonUltraGUI on Linux](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/build-app/main/linux.zip) + - [ChameleonUltraGUI on macOS](https://apps.apple.com/app/chameleon-ultra-gui/id6462919364) + - [MTools BLE on App Store](https://apps.apple.com/app/mtools-ble-rfid-reader/id1531345398) + - [MTools BLE on Google Play](https://play.google.com/store/apps/details?id=com.mtoolstec.mtoolsLite) + +2. Connect your Chameleon via USB or BLE + +3. Open application + +4. Enjoy diff --git a/sdk.md b/sdk.md new file mode 100644 index 0000000..348ac6f --- /dev/null +++ b/sdk.md @@ -0,0 +1,12 @@ +# SDKs + +SDKs for Chameleon, useful if you want to develop your own application to control Chameleon. + +## [taichunmin/chameleon-ultra.js](https://github.com/taichunmin/chameleon-ultra.js) + +[![GitHub Repo stars](https://img.shields.io/github/stars/taichunmin/chameleon-ultra.js?logo=github)](https://github.com/taichunmin/chameleon-ultra.js/stargazers) +[![GitHub issues](https://img.shields.io/github/issues/taichunmin/chameleon-ultra.js)](https://github.com/taichunmin/chameleon-ultra.js/issues) +[![npm](https://img.shields.io/npm/v/chameleon-ultra.js.svg?logo=npm)](https://www.npmjs.org/package/chameleon-ultra.js) +[![MIT License](https://img.shields.io/github/license/taichunmin/chameleon-ultra.js)](https://github.com/taichunmin/chameleon-ultra.js/blob/master/LICENSE) + +A JavaScript SDK for ChameleonUltra support Web Bluetooth API, Web Serial API and Node.js. There are also some demos for using the SDK. \ No newline at end of file diff --git a/technical_whitepaper.md b/technical_whitepaper.md new file mode 100644 index 0000000..4bd2668 --- /dev/null +++ b/technical_whitepaper.md @@ -0,0 +1,199 @@ +[nrf52_nfc_module_doc]: https://infocenter.nordicsemi.com/index.jsp?topic=%2Fcom.nordic.infocenter.nrf52832.ps.v1.1%2Fnfc.html + +[nxp_rc522_datasheet]: https://www.nxp.com/docs/en/data-sheet/MFRC522.pdf + +# ChameleonUltra + +Why not keep using ATXMEGA128? +First of all, it is difficult to buy chips because the lead time for the main chip is too long, and because the price +has skyrocketed. Secondly, because the interaction speed of the ATXMEGA, emulation is slow, the decryption performance +of the READER mode cannot meet the needs, and the LF support cannot be added, so we have been trying to upgrade it, such +as using the latest ARM to replace the AVR framework, and the performance will definitely be greatly improved. + +# Why nRF52840? + +NRF52840 has a built-in NFC Tag-A module, but no one seems to care about it. After playing with HydraNFC's TRF7970A and +FlipperZero's ST25R3916, the developers found that they can only emulate MIFARE Classic with a very high FDT. +We accidentally tested the NFC of nRF52840, and found that it is not only surprisingly easy to emulate a complete MIFARE +Classic card, but also has very good emulation performance, friendly data flow interaction, and very fast response, +unlike the former which is limited by the SPI bus clock rate. We also found that it has ultra-low power consumption, +ultra-small size, 256kb/1M large RAM and Flash, also has BLE5.0 and USB2.0 FS, super CortexM4F, most importantly, it is +very cheap! This is undoubtedly a treasure discovery for us! + +Below we will explain in detail how we exploited the performance of the NRF52840, and what seemingly impossible +functions have been realized with it! + +# Supported functions + +## High Frequency Attack + +| Attack Type | Tag Type | Whether the hardware supports | Does the software support | Whether the application layer supports | Note | +|--------------|:--------------:|------------------------------:|---------------------------|:--------------------------------------:|-------------------------:| +| Sniffing | No | No | No | No | | +| MFKEY32 V2 | MIFARE Classic | Support | Support | Support | MIFARE Classic Detection | +| Darkside | MIFARE Classic | Support | Support | Support | Encrypted 4 bit NAck | +| Nested | MIFARE Classic | Support | Support | Support | PRNG(Distance guess) | +| StaticNested | MIFARE Classic | Support | Support | Support | PRNG(2NT Fast Decrypt) | +| HardNested | MIFARE Classic | Support | Support | Not yet implemented | No | +| Relay attack | ISO14443A | Support | Support | Not yet implemented | No | + +## High Frequency emulation + +| Card Type | Encoding Type | Whether the hardware supports | Does the software support | Whether the application layer supports | Note | +|--------------------------------|:--------------------:|------------------------------:|---------------------------|:--------------------------------------:|-----------------------------------------:| +| Other than ISO14443A | No | No | No | No | [NRF52 NFC Module][nrf52_nfc_module_doc] | +| NTAG 21x (210-218) | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Ultralight | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Ultralight Ev1 | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Ultralight C | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Classic1K/2K/4K (4B/7B) | ISO14443A/106 kbit/s | Support | Support | Support | | +| MIFARE DESFire | ISO14443A High Rate | Only supported Low rate | Only supported Low rate | Not yet implemented | | +| MIFARE DESFire EV1 | ISO14443A High rate | Only supported Low rate | Only supported Low rate | Not yet implemented | Backward compatible | +| MIFARE DESFire EV2 | ISO14443A High rate | Only supported Low rate | Only supported Low rate | Not yet implemented | | +| MIFARE Plus | ISO14443A High rate | Only supported Low rate | Only supported Low rate | Not yet implemented | | + +## High Frequency Reader + +| Card Type | Encoding Type | Whether the hardware supports | Does the software support | Whether the application layer supports | Note | +|---------------------------------|:--------------------:|---------------------------------------------:|----------------------------------------------|:--------------------------------------:|-------------------------------------------:| +| Non <13.56MHz or ISO14443A> | No | No | No | No | [NXP RC522 Datasheet][nxp_rc522_datasheet] | +| NTAG 21x (210-218) | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Ultralight | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Ultralight Ev1 | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Ultralight C | ISO14443A/106 kbit/s | Support | Support | Not yet implemented | | +| MIFARE Classic 1K/2K/4K (4B/7B) | ISO14443A/106 kbit/s | Support | Support | Support | | +| MIFARE DESFire | ISO14443A High Rate | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates | Not yet implemented | | +| MIFARE DESFire EV1 | ISO14443A High rate | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates | Not yet implemented | Backward compatible | +| MIFARE DESFire EV2 | ISO14443A High rate | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates | Not yet implemented | | +| MIFARE Plus | ISO14443A High rate | Supports low rates, or possibly higher rates | Supports low rates, or possibly higher rates | Not yet implemented | | + +## Low Frequency Attack + +| Vulnerability Type | Tag Type | Whether the hardware supports | Does the software support | Whether the application layer supports | Note | +|--------------------|:---------:|------------------------------:|---------------------------|:--------------------------------------:|-----:| +| Sniffing | 125KHz | Support | Support | Not yet implemented | | +| Brute Force | EM410x ID | Support | Support | Not yet implemented | | + +## Low Frequency emulation + +| Card Type | Encoding Type | Whether the hardware supports | Does the software support | Whether the application layer supports | Note | +|---------------------------------|:-------------:|------------------------------:|---------------------------|:--------------------------------------:|----------------------------------------------:| +| Other than <125KHz/ASK/PSK/FSK> | No | No | No | No | Only 125 khz RF, Modulation ASK, FSK and PSK. | +| EM410x | ASK | Support | Support | Support | EM4100 is support(AD 64bit) | +| T5577 | ASK | Support | Support | Not yet implemented | | +| EM4305 | ASK | Support | Support | Not yet implemented | | +| HID Prox | FSK | Support | Support | Not yet implemented | | +| Indala | PSK | Support | Support | Not yet implemented | | +| FDX-B | ASK | Support | Support | Not yet implemented | | +| Paradox | FSK | Support | Support | Not yet implemented | | +| Keri | PSK | Support | Support | Not yet implemented | | +| AWD | FSK | Support | Support | Not yet implemented | | +| ioProx | FSK | Support | Support | Not yet implemented | | +| securakey | ASK | Support | Support | Not yet implemented | | +| gallagher | ASK | Support | Support | Not yet implemented | | +| PAC/Stanley | ASK | Support | Support | Not yet implemented | | +| Presco | ASK | Support | Support | Not yet implemented | | +| Visa2000 | ASK | Support | Support | Not yet implemented | | +| Viking | ASK | Support | Support | Not yet implemented | | +| Noralsy | ASK | Support | Support | Not yet implemented | | +| NexWatch | PSK | Support | Support | Not yet implemented | | +| Jablotron | ASK | Support | Support | Not yet implemented | | + +## Low Frequency Reader + +| Card Type | Encoding Type | Whether the hardware supports | Does the software support | Whether the application layer supports | Note | +|---------------------------------|:-------------:|------------------------------:|---------------------------|:--------------------------------------:|----------------------------------------------:| +| Other than <125KHz/ASK/PSK/FSK> | No | No | No | No | Only 125 khz RF, Modulation ASK, FSK and PSK. | +| EM410x | ASK | Support | Support | Support | | +| T5577 | ASK | Support | Support | Support(Write) | | +| EM4305 | ASK | Support | Support | Not yet implemented | | +| HID Prox | FSK | Support | Support | Not yet implemented | | +| Indala | PSK | Support | Support | Not yet implemented | | +| FDX-B | ASK | Support | Support | Not yet implemented | | +| Paradox | FSK | Support | Support | Not yet implemented | | +| Keri | PSK | Support | Support | Not yet implemented | | +| AWD | FSK | Support | Support | Not yet implemented | | +| ioProx | FSK | Support | Support | Not yet implemented | | +| securakey | ASK | Support | Support | Not yet implemented | | +| gallagher | ASK | Support | Support | Not yet implemented | | +| PAC/Stanley | ASK | Support | Support | Not yet implemented | | +| Presco | ASK | Support | Support | Not yet implemented | | +| Visa2000 | ASK | Support | Support | Not yet implemented | | +| Viking | ASK | Support | Support | Not yet implemented | | +| Noralsy | ASK | Support | Support | Not yet implemented | | +| NexWatch | PSK | Support | Support | Not yet implemented | | +| Jablotron | ASK | Support | Support | Not yet implemented | | + +## Low Frequency Modulation + +| Modulation Type | wav | +|-----------------|------------------------------------:| +| PSK | ![PSK WAV](images/measured-psk.png) | +| FSK | ![FSK WAV](images/measured-fsk.png) | +| ASK | ![ASK WAV](images/measured-ask.png) | + +# Ultra-low power consumption + +It integrates a high-performance and low-power NFC module inside. When the NFC unit is turned on, the total current of +the chip is only 5mA @3.3V. +The underlying interaction is done independently by the NFC unit and does not occupy the CPU. +In addition, the nRF52840 itself is a high-performance low-power BLE chip, and the encryption and calculation process is +only 7mA @3.3V. It can greatly reduce the battery volume and prolong the working time. That is to say, the 35mAh 10mm* +40mm button lithium battery can guarantee to be charged once every half a year under the working condition of swiping +the card 8 times a day for 3 seconds each time. Full potential for everyday use. + +# Not just UID, but a real and complete MIFARE Classic emulation + +We can easily and completely emulate all data and password verification of all sectors, and can customize SAK, ATQA, +ATS, etc. Similar to an open CPU card development platform, 14A interaction of various architectures can be easily +realized. + +# Super compatibility with low-power locks using batteries + +The structure of the old Chameleon AVR is slow to start during emulation. Faced with a battery-powered low-power lock +and an integrated lock on the door, it will be frequently interrupted, and the verification interaction cannot be +completed completely, resulting in no response when swiping the card. + +In order to reduce power consumption, the battery lock will send out a field signal as short as possible when searching +for a card, which is no problem for the original card, but it is fatal for the MCU emulated card. Cards or mobile smart +bracelets emulated by the MCU cannot wake up and respond in such a short time, so many battery locks cannot open the +door, which greatly reduces the user experience. + +This project specially optimizes the start-up and interaction logic and antenna for low-power reading heads. After +testing a variety of common low-power reading heads, they can open the door perfectly by swiping the card. + +# Ultra-fast response speed and low interaction delay(MIFARE Classic) + +| Tag/Emulation | FDT | "**_FDT_**" Rating | +|----------------------|:-----------------------------------------------------------------------------:|:--------------------------------------------------------------------------------:| +| Standard MIFARE Card | ![Standard_m1_s50](images/fdt_standard_s50.png) | ⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐ | +| Chameleon Ultra | ![Chameleon Ultra](images/fdt_chameleon_ultra.png) | ⭐⭐⭐⭐⭐⭐⭐⭐ | +| Proxmark3 Rdv4.01 | ![Proxmark3_Rdv4_RRG_(Firmware build at 20201026)](images/fdt_pm3_rdv401.png) | ⭐⭐⭐⭐ | +| RedMi K30 | ![Xiaomi_k30u_smartkey](images/fdt_redmi_k30.png) | ⭐⭐⭐⭐⭐⭐ | +| Chameleon Tiny | ![Chameleon Tiny](images/fdt_chameleon_tiny.png) | ⭐⭐⭐⭐⭐ | +| Flipper Zero | ![Flipper Zero](images/fdt_flipper_zero.png) | ⭐⭐ | + +# 256kB super large RAM cooperates with RC522 to enable attacks + +| Attack Type | CLI | +|--------------|:----------------------------------------------------------:| +| MFKEY32 V2 | ![attack_MIFARE_mfkey32](images/cli_mfkey32v2.png) | +| Darkside | ![attack_MIFARE_darkside](images/cli_darkside.png) | +| Nested | ![attack_MIFARE_nested](images/cli_nested.png) | +| StaticNested | ![attack_MIFARE_staticnested](images/cli_staticnested.jpg) | +| HardNested | Coming Soon | +| Relay attack | Coming Soon | + +# Hardware frame diagram + +![hw frame diagram](images/hardware_overview.png) + +# Birth of the project + +When the project got open-sourced, DXL shared a few notes in [issue #1](https://github.com/RfidResearchGroup/ChameleonUltra/issues/1#issuecomment-1455016381). + +**Hardware:** ChameleonUltra and ChameleonLite hardware were carefully designed by Proxgrind team. They inherit the style of ChameleonTiny, which is very consistent with Olaf's style. Yes, whether it is Proxmark3 RDV4 or Chameleon Tiny, Olaf likes to reduce the size as much as possible under the extreme performance, making it easy to carry, unique in appearance and full of technology. At the same time, it is a pity that the volume of Chameleon Ultra brings inconvenience to most people for PCBA manufacturing and firmware development and testing. Therefore, we feel that we need to provide a development board based on ChameleonUltra with a larger volume. The components of this development board is packaged with common volume to make it easy to weld, and we also reserved GPIO interface and SWD interface. And this development board is also open source. If enthusiasts are interested, they can build a Chameleon Ultra from scratch. Of course, if there is no welding tool, we also provide formed development boards for sale (moderate price). + +**Firmware:** Chameleon Ultra is a very powerful platform. We can develop various 14A protocol card simulations based on this platform. In terms of high-frequency card simulation, DXL has completed the development of high-performance MifareClassic Mini ->S50 ->S70 card. However, the development of cards for other technologies has not been completed, such as UL, UL-C, NTAG, etc. In terms of low-frequency card simulation, DXL has completed the development of EM410x, but the development of other technology cards has not been completed, such as FSK and PSK-related technology cards. For card reader, DXL has completed the reading, writing and decryption of M1 card, reading EM410x and writing to T5577. Others, such as the reading and writing of UL card and NTAG card, are not completed yet. + +**Client:** At present, ChameleonUltra uses python to develop the CLI, cooperate with independent exe to perform the decryption task, and complete the decoupling of the business logic of the CLI and the decryption algorithm logic. Due to time reasons, DXL only completes commands such as device connection, M1 card data upload, M1 card detection log download and decryption, M1 card read and write block, and so on. The complete nested, rdsc, and autopwn instructions like PM3 have not yet been implemented, which may require our joint efforts. Finally, I believe that Chameleon Ultra is definitely not limited to CLI as a way of device interaction. Perhaps we can further develop PC-side GUI, and develop IOS and Android APP. USB+BLE support makes everything possible. diff --git a/troubleshooting.md b/troubleshooting.md new file mode 100644 index 0000000..15cee06 --- /dev/null +++ b/troubleshooting.md @@ -0,0 +1,123 @@ +# Hardware + +## Difficulties to get emulation working properly + +Try with waking up the Chameleon by pressing a button before presenting it to the reader. Try with keeping some 2-3 cm distance to the reader. + +## Difficulties to get the LF working properly + +The LF antenna is on a second PCB attached to the main PCB via little screws which also serve as electric connection. +It has reported that on some devices the electric connection is not good, some glue or resin residues may interfere. +You can try to dismantle very gently the screws and PCB, clean them and put them back in place. +Be very careful the screws have been reported to be quite fragile so be gentle with them! + +# BLE + +## Difficulties connecting using BLE + +On Android make sure your location is turned, as that allows for scanning of bluetooth devices. + +## Difficulties to use BLE + +After BLE pairing, both the phone and ChameleonUltra will save a secret key for encrypted communication. If either party deletes the pairing record, it will result in communication failure. If Bluetooth cannot be connected, clearing the pairing information on the other side can solve the problem: + +* Find the Bluetooth settings in the phone's system settings and cancel pairing with the ChameleonUltra. +* In the CLI of ChameleonUltra, execute the `hw settings bleclearbonds` command to clear all pairing records. + +Default BLE connect key(passkey) is `123456` + +# DFU + +## Error when attempting DFU upgrade with `nrfutil` + + +``` +[00:00:00] ------ 0% [id:9] Failed, [sdfu] [json.exception.type_error.302] type must be string, but is null +``` +or +``` +[00:00:00] ------ 0% [2/2 ...] Failed, [sdfu] +``` + +### Check permissions and ModemManager + +Check the serial port permissions and if under Linux, make sure ModemManager is not interfering with your Chameleon. +The proposed [udev/rules.d file](../resource/driver/79-chameleon-usb-device-blacklist-dialout.rules) may help you (and add your user to the dialout group). + +### Check `hw_version` of your DFU package + +Another cause of this error is a mismatch between `hw_version` of the DFU package you want to use and your hardware. You can check it with the following command. + +``` +nrfutil nrf5sdk-tools pkg display my-dfu-file.zip |grep hw_version +``` +`hw_version` must be equal to `0` for the Ultra and `1` for the Lite. + +# CLI tools compilation + +## ProxSpace: cmake error + +The following error has been reported on some ProxSpace installations (why on some and not all is still unclear) + +``` +pm3 ~/ChameleonUltra/software/src$ cmake . +-- Building for: Ninja +-- The C compiler identification is GNU 10.3.0 +-- Detecting C compiler ABI info +-- Detecting C compiler ABI info - failed +-- Check for working C compiler: C:/Users/moeya/Desktop/Chamelion/ProxSpace/msys2/mingw64/bin/cc.exe +-- Check for working C compiler: C:/Users/moeya/Desktop/Chamelion/ProxSpace/msys2/mingw64/bin/cc.exe - broken +CMake Error at C:/Users/moeya/Desktop/Chamelion/ProxSpace/msys2/mingw64/share/cmake-3.21/Modules/CMakeTestCCompiler.cmake:69 (message): + The C compiler + + "C:/Users/xxx/ProxSpace/msys2/mingw64/bin/cc.exe" + + is not able to compile a simple test program. +``` + +This is due to a version of ninja not aware of the Windows paths. Fix: + +``` +pacman -R ninja --noconfirm +pacman -S mingw-w64-x86_64-ninja --noconfirm +``` + +## cmake: Undefined reference to "pthread_create" + +It has been reported that on some Linux systems cmake doesnt find pthread. + +Make sure to have libpthread installed, the package may be named differently on your distro. + +On ubuntu and same based systems it is the following command: +``` +sudo apt install libpthread-stubs0-dev +``` + +If this doesnt fix it, you may need to set pthread in the LDFLAGS enviroment variable, this can be done by running the command with the enviroment variable at the beginning: + +``` +LDFLAGS=-pthread cmake .. +``` + +If the error still persists you may also need to provide a specific compiler version, you do that by adding the -DCMAKE_C_COMPILER argument: + +``` +LDFLAGS=-pthread cmake -DCMAKE_C_COMPILER=gcc-11 .. +``` + +The compiler needs to be installed too ofcourse, the package name may be differently on your distro. + +On ubuntu and same based systems its the following command: + +``` +sudo apt install gcc-11 g++-11 +``` + +The following ```cmake --build . --config Release``` should work again without modification. + +# CLI usage + +## InvalidException: Device unsupported cmd + +You need to update the firmware of your Chameleon. +