From 45c6ef14d01a52ac13b9f5fe69f0bbab013fdc46 Mon Sep 17 00:00:00 2001
From: Rahix <rahix@rahix.de>
Date: Tue, 16 Jul 2019 09:41:25 +0200
Subject: [PATCH] chore: Rewrite README to point to new docs
Signed-off-by: Rahix <rahix@rahix.de>
---
README.md | 138 ++++++------------------------------------------------
1 file changed, 15 insertions(+), 123 deletions(-)
diff --git a/README.md b/README.md
index 578b4666b..f1e790c09 100644
--- a/README.md
+++ b/README.md
@@ -1,132 +1,29 @@
# card10 Firmware Readme
-## Setup
-To compile the firmware you need the following:
+Firmware for the card10 badge for the Chaos Communication Camp 2019.
-- `meson`(>0.40.0)
-- `arm-none-eabi-gcc` (package might be called `gcc-arm-none-eabi`)
-- `arm-none-eabi-binutils` (package might be called `binutils-arm-none-eabi`)
-- `arm-none-eabi-newlib` (package might be called `libnewlib-arm-none-eabi`)
-- `python3`
-- `python3-crc16` (`pip3 install --user crc16`)
+We keep documentation in the `Documentation/` subdirectory. You can find a
+rendered version over at <https://firmware.card10.badge.events.ccc.de/>.
-### Compiler (`arm-none-eabi-gcc`)
-Install the cross-compiler and debugger either from your distributions repositories, or alternatively download a precompiled toolchain from [ARM](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads).
+## How To Help
+If you want to help us ensure the card10 will have been exactly as we reconstructed from the audio-logs we recovered, please head over to our [wiki](https://card10.badge.events.ccc.de/en/firmware/), or directly to the [issue tracker](https://git.card10.badge.events.ccc.de/card10/firmware/issues?sort=label_priority).
-On Ubuntu, the package is called `gcc-arm-none-eabi`.
+## How To Build
+A full guide for building is available in the docs as [How To Build](https://firmware.card10.badge.events.ccc.de/how-to-build.html).
-If you downloaded the toolchain from ARM, you need to adjust `card10-cross.ini`. Under `[binaries]`, prefix the names of each executable with the full path to the extracted toolchain directory. Like `/path/to/gcc-arm-none-eabi-8-2018-q4-major/bin/arm-none-eabi-gcc`.
+## How To Flash
+Flasing with or without a debugger is described in detail in [How To Flash](https://firmware.card10.badge.events.ccc.de/how-to-flash.html).
-### Compiling the card10 firmware
-```bash
-# Configure the build system
-./bootstrap.sh
-# Start the build
-ninja -C build/
-```
+## Debugger
+If you have a debugger, head over to our [Debugger](https://firmware.card10.badge.events.ccc.de/debugger.html) page to learn how to use it.
-You can also build individual targets using
-```bash
-ninja -C build/ <target>
-```
+---
-where `target` is one of
- - `hw-tests/bmatest/bmatest.bin` - Test for `BMA400`
- - `hw-tests/bmetest/bmetest.bin` - Test for `BME680`
- - `hw-tests/ecgtest/ecgtest.bin` - Test for `MAX30003` ECG
- - `hw-tests/hello-world/hello-world.bin` - General Demo
- - `hw-tests/imutest/imutest.bin` - Compass Test
- - `hw-tests/ips/ips.bin` - Display Test
- - `hw-tests/dual-core/dual-core{0,1}.bin` - Dual-Core Demo
-
-### GDB (`arm-none-eabi-gdb`)
-
-If you want to debug code or replace the bootloader, you need OpenOCD and GDB.
-
-Use `arm-none-eabi-gdb` (might be packaged as `gdb-arm-none-eabi` or get it from the binary distribution above).
-
-Add the following line to your `~/.gdbinit` file:
-```
-add-auto-load-safe-path <PATH TO THIS REPOSITORY>
-```
-This allows gdb to use our .gdbinit files without specifying them on the command line.
-
-
-### OpenOCD
-If you want to debug code or replace the bootloader, you need OpenOCD and GDB.
-
-Get OpenOCD from [our fork](https://git.card10.badge.events.ccc.de/card10/openocd) of [Maxim's fork](https://github.com/maximmbed/openocd):
-
-```bash
-git clone https://git.card10.badge.events.ccc.de/card10/openocd.git
-cd openocd
-
-git submodule update --init
-./bootstrap
-./configure --disable-werror
-make -j8
-```
-
-Make sure that the `CMSIS-DAP Compliant Debugger` is set to `yes(auto)` after running `./configure` (you might need to install libusb and other USB related libraries).
-If you get errors making the documentation you can `touch doc/openocd.info` to skip it and continue with 'make'.
-
-Please run `make install` after removing any already installed OpenOCD version. Otherwise please always specify the full path to openocd (the binary is under `src/openocd`, when calling `openocd`.
-
-Run OpenOCD from the root `openocd/scripts` directory in this repository like this: `openocd -f interface/cmsis-dap.cfg -f target/max32665.cfg`. It should display something similar to:
-
-```
-Info : CMSIS-DAP: SWD Supported
-Info : CMSIS-DAP: FW Version = 1.0
-Info : CMSIS-DAP: Interface Initialised (SWD)
-Info : SWCLK/TCK = 0 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
-Info : CMSIS-DAP: Interface ready
-Info : clock speed 2000 kHz
-Info : SWD DPIDR 0x2ba01477
-Info : max32xxx.cpu: hardware has 6 breakpoints, 4 watchpoints
-Info : Listening on port 3333 for gdb connections
-
-```
-
-## Debugger Connection
-If you have the debugger provided with the `card10`, connect it as follows:
- - `HDK`: This connection provides debugging (SWD) and UART
- - `DEV`: This connection provides power (battery charger) and the native USB connection (bootloader)
- - `USB-C`: Connect the proved USB-C cable with the side which has the blue dot, so the blue dots have the same side
-
-Now connect the USB-C cable, so the name of the cable manufacturer facing downwards (i.e. is not visible when looking at the display).
-
-## Flashing
-Run `arm-none-eabi-gdb` in the applications folder. It should connect to OpenOCD and say something like:
-```
-TMR_Delay (tmr=tmr@entry=0x40010000, us=us@entry=10000, sys_cfg=sys_cfg@entry=0x0) at Source/tmr_utils.c:59
-59 while (TMR_TO_Check(tmr) != E_TIME_OUT) {}
-(gdb)
-```
-
-Enter `load`. It should say something like:
-```
-(gdb) load
-Loading section .text, size 0x12514 lma 0x10010000
-Loading section .ARM.exidx, size 0x8 lma 0x10022514
-Loading section .data, size 0x8d8 lma 0x1002251c
-Start address 0x10012160, load size 77300
-Transfer rate: 19 KB/sec, 11042 bytes/write.
-(gdb)
-```
-
-To run the program, type: `reset` (which runs `mon mww 0x40000004 0x80000000`). This is a quirk as the prototypes to not have a reset line exposed to the debugger. Will be solved with production hardware.
-
-Important: You need to flash the bootloader first and make sure that there is no `card10.bin` file on the internal file system. Otherwise your program might not boot, or is overwritten by the bootloader.
-
-TODO: Provide a make command to flash card10.
-
-## Debugging
-After flashing and the initial reset using `reset`, you can say `mon reset halt` and then `continue`. You can now debug as usual.
-(`reset` is defined in `.gdbinit` and runs `mon mww 0x40000004 0x80000000`)
+# Old README Contents:
+TODO: Move over into new docs
## Serial Console
-card10 outputs debug information on the serial console. Baudrate is 115200. The provided USB adapter creates a CDC device (under Linux /dev/ttyACM0). You can use screen to open and view it: `screen /dev/ttyACM0 115200`.
-
+Learn more about [card10's Serial Console](https://firmware.card10.badge.events.ccc.de/pycardium/overview.html#serial-console).
## Bootloader
The bootloader is used to flash card10 without an external debugger. It exposes the file system via USB and accepts a `card10.bin` file as firmware image.
@@ -141,8 +38,3 @@ IMPORTANT: The prototypes have the USB data lines reversed. Use the provided USB
Run `./build_image`. TODO: Add to meson
The tool uses Python to generate a CRC. Make sure to have `python-crc16` installed.
-
-## Examples
-### Hello World
-Turns on the display, enumerates I2C, prints debug information on the console.
-
--
GitLab