README ====== About ----- When it comes to flash a [coreboot][] or [libreboot][] machine, the Zerocat Chipflasher is a very special tool: - it comes with free documentation - it runs with free-software - its board layout is free-design hardware - it uses a free-design microcontroller ...and you can solder your own device, it is a do-it-yourself project! The projects mentioned above provide free firmware replacements, which usually require to externally flash onboard SPI flash chips of selected targets. Machines like the Lenovo ThinkPad X200 or X220 Notebook are high quality products which are well supported. These projects aim to support user freedom, but often suffer to be dependent on external flashers which are not compatible in that point. The Zerocat Chipflasher is meant to fill that gap. ### Project’s Naming Convention The project’s internal name simply is _chipflasher_, the firmware is called `kick` and the host software --- located under the `host/` folder --- is called `connect`. The entire project is hosted under the umbrella of the Zerocat Label, thus referencing to this project in public should be done by using the name **Zerocat Chipflasher**. Internet Resources ------------------ ### Websites The webpage of the [Zerocat Chipflasher][chipflasher-webpage] is a part of the [Zerocat Website][]. ### Shop We offer products and services in Berlin (Germany), as like: - free-design devices and microcontrollers - coreboot and libreboot flash services - pre-flashed laptops and desktop boards - workshops and more... Please check shop information, portfolio and prices on the [Zerocat Website][]. ### Email Please send your questions, feedback, bug reports or product requests to [zerocat@posteo.de][zerocat-email]. A public OpenPGP key is available upon request. ### Mailing List The Zerocat Label is using encrypted email for its mailing list; currently, we don’t have a general address for it. If you want to contact the ML, please write an email to [zerocat@posteo.de][zerocat-email] and your mail will be forwarded. ### Git Repository - Zerocat Chipflasher Repository git://zerocat.org/zerocat/projects/chipflasher Prerequisites ------------- ### Recommended Hardware As the chipflasher is operated over a serial port, we recommend to use a host computer with RS232 port, running with [libreboot][] or blobless [coreboot][] BIOS. In [How To Use][], some example machines are listed in section 'Typical Setup'. ### GNU/Linux OS We assume that you are running a GNU/Linux-libre Operating System like [Trisquel][], for example. Very essential tools that allow building the documentation should be installed first, as like... - [Git][] (We recommend a recent version like `git version 2.10.0`.) - [Doxygen][] - [GNU Make][] - The gEDA/gaf subset of tools from the [gEDA-project][]. - [PCB][], the Printed Circuit Board Editor - [GNU sed], the GNU stream editor ### Clone Repository As a next step, please open a terminal, create a zerocat project folder and clone the public git repository onto your harddrive: $ mkdir -p ~/zerocat/projects/ $ cd ~/zerocat/projects/ $ git clone git://zerocat.org/zerocat/projects/chipflasher Now you should have a folder `~/zerocat/projects/` with subfolder `chipflasher/`. #### Version Checkout Instead of using the default tip of branch _master_ which could leave you with inconsistent sources, you should find the most recent version tag and perform a `git checkout`: $ cd ~/zerocat/projects/chipflasher/ $ git describe --abbrev=0 This will give you the most recent version tag ``. $ git checkout @note If you want to match the version of your specific physical device, lookup the version tag on its front-panel sticker. You may use `$ git tag` to get an overview of available tags and see if one matches. Example: In case your device carries the info 'Version: board-edition-1', please perform a corresponding checkout like so: `$ git checkout board-edition-1` @note If you want to try a different version tag with your specific device, note that it is up to you to verify that your hardware is still compatible with the sources. [Version History][] and [Board Version History][] will hopefully help you to figure that out. ### Generate the Chipflasher Documentation Change into your local `zerocat/projects/chipflasher/doc` folder and type `make`: $ cd ~/zerocat/projects/chipflasher/doc/ $ make In folder `generated-documentation`, this will generate three `index.html` files which are all linked with each other so that you can freely navigate between them using your favorite browser: - `chipflasher/html/index.html` - `connect/html/index.html` - `board/html/index.html` ### Install Software Build Dependencies Please read [Software Tools][] and install the required programs before you proceed. Get Started ----------- You should now be ready to proceed with [How To Use][]. Licenses -------- The files that ship with the Zerocat Chipflasher fall into five categories: 1. hardware design sources (files from gEDA-gschem, PCB-Designer, OpenSCAD, LibreCAD, etc.) 2. code sources (text files with syntax of C, ASM, Makefile, Propeller-Load Configuration, Doxyfile, bash, scheme, etc.) 3. documentation files (markdown, simple text) 4. graphics and photos (files made with Scribus, Inkscape, Gimp, etc.) 5. logo files (files made with Scribus, Inkscape, Gimp, etc.) In general the following rules apply: - If not otherwise stated within this project, all files are copyrighted: `Copyright (C) 2015, 2016, 2017, 2018 Kai Mertens `. - A license header is placed within the files if applicable. - "1. hardware design sources" and "2. code sources" are licensed under the GNU GPLv3 or later. The license itself is shipped as [COPYING](COPYING.md). - "3. documentation files" are licensed under GNU FDL 1.3 or later, without invariant sections, front-cover texts or back-cover texts. This license is shipped with [COPYING-DOCUMENTATION](COPYING-DOCUMENTATION.md). - "4. graphics and photos" are released under the CC BY-SA 4.0 International Public License. The URL to the license text is shipped with [COPYING-GRAPHICS](COPYING-GRAPHICS.md). - "5. logo files" are released under the Zerocat Logo License. This license is shipped with [COPYING-LOGO](COPYING-LOGO.md). Development ----------- Initially, development has been done by playing around with a ThinkPad X60 motherboard in 2015. Please note that the project itself is developed on a liberated ThinkPad X60 with a preflashed libreboot image on it, thus forming a quite complete free software workbench. In March 2016, a first bunch of Thinkpad X200 laptops with Macronix and Winbond chips have been flashed successfully. Since then, the chipflasher has been used for more targets, and its adaption of code, board circuits and documentation went straight-forward into the public git repository. [Supported Devices][] gives you a full list of tested targets. ### The Team - Kai Mertens - Tomás Zerolo - Holger Kienle - Ricardo Wurmus - ...and pioneer customers, who give valuable feedback. Kevin Keijser from [www.librepractice.org][librepractice] spent a bunch of testboards, is testing the chipflasher, and is liberally sharing his coreboot experience with us. ### Your Support You can help to improve and support the chipflasher in different situations: - Buy one and provide feedback. - Build your own and tell us how to improve the documentation. - Provide your coreboot compatible device for testing purposes. - Your donations are very welcome! Please see [www.zerocat.org/sales.html][account] for bank account details. - last but not least: Spread the word, tell people about it! ### Free System Distribution Guidelines (GNU FSDG) We check the Zerocat Chipflasher distribution according to the [GNU FSDG][].@n If you discover mistakes, please report to [zerocat@posteo.de][zerocat-email] and we will fix them. [Trisquel]: https://www.trisquel.info/ [Git]: https://git-scm.com/ [Doxygen]: http://www.stack.nl/~dimitri/doxygen/index.html [GNU Make]: https://www.gnu.org/software/make/ [GNU sed]: https://www.gnu.org/software/sed/ [gEDA-project]: http://www.geda-project.org/ [PCB]: http://pcb.geda-project.org/index.html [GNU FSDG]: https://www.gnu.org/distros/free-system-distribution-guidelines.html [coreboot]: https://www.coreboot.org/ [libreboot]: https://www.libreboot.org/ [librepractice]: https://www.librepractice.org/ [zerocat-email]: mailto:zerocat@posteo.de [Zerocat Website]: http://www.zerocat.org/ [chipflasher-webpage]: http://www.zerocat.org/chipflasher-board-edition-1.html [account]: http://www.zerocat.org/sales.html [README]: README.md [Supported Devices]: supported-devices.md [How To Use]: how-to-use.md [Software Tools]: software-tools.md [Version History]: version-history.md [Board Version History]: board-version-history.md ----------------------------------------------------------------------- @copyright Copyright (C) 2017, 2018 Kai Mertens @n Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled: [GNU Free Documentation License](COPYING-DOCUMENTATION.md)