diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 0000000..7f7c83f --- /dev/null +++ b/HACKING.md @@ -0,0 +1,72 @@ +The following information will focus on the software development. + +board +===== + +The BusVoodoo uses a [custom board](https://bus.cuvoodoo.info/manual/index.html#_hardware_development) based on a [STM32F103RC](http://www.st.com/en/microcontrollers/stm32f103rc.html) micro-controller. + +code +==== + +dependencies +------------ + +To develop the firmware, following Linux packages are required: + +- _arm-none-eabi-gcc_ to compile the source code +- _arm-none-eabi-binutils_ to create the firmware binaries +- _arm-none-eabi-gdb_ to debug the firmware +- _rake_ automate development steps +- _openocd_ to flash and debug over SWD (when using an ST-Link V2 adapter) +- _doxygen_ to compile the documentation + +The source code uses the [libopencm3](http://libopencm3.org/) library. +The projects is already a git submodules. +It will be initialized when compiling the firmware. +Alternatively you can run once: `git submodule init` and `git submodule update`. + +firmware +-------- + +To compile the firmware files run `rake`. +This will generate two firmware: + +- _bootloader_: a USB DFU bootloader +- _application_: the main application + +documentation +------------- + +To generate doxygen documentation run `rake doc`. +The documentation describing all files, functions, and variables will be available in the _doc_ folder. + +Further comments are in the source code. + +flash +----- + +There are two firmware images: `bootloader` and `application`. +The `bootloader` image allows to flash the `application` over USB using the DFU protocol. +The `bootloader` is started first and immediately jumps to the `application` if it is valid and the DFU mode is not forced. +The `application` image is the main application and is implemented in `application.c`. + +The `bootloader` image will be flashed using SWD (Serial Wire Debug). +For that you need an SWD adapter. +The `Makefile` uses a Black Magic Probe (per default), or a ST-Link V2 along OpenOCD software. +To flash the `booltoader` using SWD run `rake flash_booloader`. + +Once the `bootloader` is flashed it is possible to flash the `application` over USB using the DFU protocol by running `rake flash`. +The `application` advertises USB DFU support (along with the USB CDC ACM class). +If the application is broken, force the bootloader to start the DFU mode by shorting the contacts marked as DFU on the board while powering up. +It is also possible to flash the `application` image using SWD by running `rake flash_application`. + +debug +----- + +SWD also allows to debug the code running on the micro-controller using GDB. +To start the debugging session run `rake debug`. + +USB +--- + +The firmware offers serial communication over USART 1 and USB (using the CDC ACM device class). diff --git a/README.md b/README.md index 65295b5..bdae88e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -This firmware for the [BusVoodoo](https://bus.cuvoodoo.info/). +This is the firmware for the [BusVoodoo](https://bus.cuvoodoo.info/). project ======= @@ -11,79 +11,40 @@ This tool allows to quickly communicate with various other electronic devices. An overview of the BusVoodoo can be found [here](https://bus.cuvoodoo.info/) A more detailed manual is available [here](https://bus.cuvoodoo.info/manual/). -The following information will focus on the software development. - -board -===== - -The BusVoodoo uses a [custom board](hhttps://bus.cuvoodoo.info/manual/index.html#_hardware_development) based on a [STM32F103RC](http://www.st.com/en/microcontrollers/stm32f103rc.html) micro-controller. - -code -==== - -dependencies ------------- - -To develop the firmware, following Linux packages are required: - -- _arm-none-eabi-gcc_ to compile the source code -- _arm-none-eabi-binutils_ to create the firmware binaries -- _arm-none-eabi-gdb_ to debug the firmware -- _rake_ automate development steps -- _openocd_ to flash and debug over SWD (when using an ST-Link V2 adapter) -- _doxygen_ to compile the documentation - -The source code uses the [libopencm3](http://libopencm3.org/) library. -The projects is already a git submodules. -It will be initialized when compiling the firmware. -Alternatively you can run once: `git submodule init` and `git submodule update`. - -firmware --------- - -To compile the firmware files run `rake`. -This will generate two firmware: - -- _bootloader_: a USB DFU bootlaoder -- _application_: the main application - -documentation -------------- - -To generate doxygen documentation run `rake doc`. -The documentation describing all files, functions, and variables will be available in the _doc_ folder. - -Further comments are in the source code. - -flash ------ - -There are two firmware images: `bootloader` and `application`. -The `bootloader` image allows to flash the `application` over USB using the DFU protocol. -The `bootloader` is started first and immediately jumps to the `application` if it is valid and the DFU mode is not forced. -The `application` image is the main application and is implemented in `application.c`. - -The `bootloader` image will be flashed using SWD (Serial Wire Debug). -For that you need an SWD adapter. -The `Makefile` uses a Black Magic Probe (per default), or a ST-Link V2 along OpenOCD software. -To flash the `booltoader` using SWD run `rake flash_booloader`. - -Once the `bootloader` is flashed it is possible to flash the `application` over USB using the DFU protocol by running `rake flash`. -The `application` advertises USB DFU support (along with the USB CDC ACM class). -If the application is broken, force the bootloader to start the DFU mode by shorting the contacts marked as DFU on the board while powering up. -It is also possible to flash the `application` image using SWD by running `rake flash_application`. - -debug ------ - -SWD also allows to debug the code running on the micro-controller using GDB. -To start the debugging session run `rake debug`. USB --- -The firmware offers serial communication over USART1 and USB (using the CDC ACM device class). +The firmware offers serial communication over USART 1 and USB (using the CDC ACM device class). -You can also reset the board by setting the serial width to 5 bits over USB. -To reset the board run `rake reset`. -This only works if provided USB CDC ACM is running correctly and the micro-controller isn't stuck. +board +===== + +The BusVoodoo uses the a [custom board](https://bus.cuvoodoo.info/manual/index.html#_hardware_development) based on an [STM32F103RC](http://www.st.com/en/microcontrollers/stm32f103rc.html) micro-controller. + +firmware +======== + +binaries +-------- + +There are two firmware files: + +- _bootloader_: a USB DFU bootloader +- _application_: the main application + +flash +----- + +How to flash the binary firmware files in described in the [manual](https://bus.cuvoodoo.info/manual/index.html#_flashing). + +source +------ + +The source code is available in [git](https://git.cuvoodoo.info/busvoodoo_firmware/), under the **busvoodoo** branch (or **busvoodoo_v0** for hardware version 0). +This firmware also uses the [LibOpenCM3](http://libopencm3.org/) library. + +development +----------- + +For information about firmware development, check the _HACKING.md_ instructions.