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 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. 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 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 <chipflasher-version-tag>.

$ git checkout <chipflasher-version-tag>

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; 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:

hardware design sources (files from gEDA-gschem, PCB-Designer, OpenSCAD, LibreCAD, etc.)
code sources (text files with syntax of C, ASM, Makefile, Propeller-Load Configuration, Doxyfile, bash, scheme, etc.)
documentation files (markdown, simple text)
graphics and photos (files made with Scribus, Inkscape, Gimp, etc.)
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 <kmx@posteo.net>.
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.
"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.
"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.
"5. logo files" are released under the Zerocat Logo License. This license is shipped with COPYING-LOGO.

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 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 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.
If you discover mistakes, please report to zerocat@posteo.de and we will fix them.

Copyright: Copyright (C) 2017, 2018 Kai Mertens kmx@p.nosp@m.oste.nosp@m.o.net
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