-
Notifications
You must be signed in to change notification settings - Fork 196
Setting up Firmware Development Software
Building and installing the firmware is quite easy. However, please read and follow the instructions outlined below before asking. If you feel that the instructions can be improved, extended, shortened: Feel free to do so and share your knowledge with all of us. Log into your GitHub account and start improving this document. Thank you!
If you want to contribute your improvements, read the guidelines for contributing to learn how to do this.
If you want to be seriously involved in firmware development, the use of a cheap real-time debugger such as the ST-Link is a real time-saver. Unfortunately, Rev 0.5 of the UI Board removes the previously available connections from the P8 header to the Debug interface and repurpose the pins. For that reason it is going to be very difficult to connect the debugger to the CPU. While it is not impossible to wire it up, TRY TO AVOID UI Board Rev. 0.5 if you plan to use the debugging capabilities at any later time.
Normal use of the mcHF should not seriously suffer from this problem.
The project uses gcc for compilation. Other compilers have not been tested and are not supported by the build environment. Feel free to add support for other compilers.
Currently gcc versions 4.9 and 5.2 are being used with success. Older releases had issues during linking, so no official support for those, use of older releases is not recommended.
On many newer distributions you can use the compiler environment provided as packages with the distribution. If it is a gcc 4.9 or newer, you should be fine. To get the newest compiler, you can look at the GCC ARM Embedded Project. However, for now we recommend to stick with the recommended configurations first. Feel free to add more instructions to this wiki.
If you happen to run a Raspberry Pi or similar ARM based linux machines, you could use the provided compiler, but this is not tested.
Use apt install gcc-arm-linux-gnueabihf to get the newest available compiler release including all tools required to build the firmware.
Use of standard compiler and tools packages included works for Ubuntu 15.04 and newer. Use apt-get install gcc-arm-linux-gnueabihf to get the newest available compiler release including all tools required to build the firmware.
Install openocd if you plan to run hardware assisted debugging.
Use the instructions given below for Debian Jessie, installing the backport works perfectly to get gcc 4.9.
sudo add-apt-repository "deb http://ftp.debian.org/debian jessie-backports main"
sudo apt-get update
sudo apt-get install -t jessie-backports -y --force-yes gcc-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib openocd
On Windows you can follow two approaches. You may go for a IDE based environment or use a command line build approach. For command line builds, you will have to use a Unix emulation (MinGW) or Bash on Ubuntu on Windows (WSL available on Windows 10). For IDE builds you will have to use the GCC Compiler for ARM.
The GCC ARM Embedded Project provides installers for Windows and more. Download the most recent installer and run it, leaving all settings to the defaults.
MinGW provides a Unix emulation, we simply install all the nice Unix tools and can run a Makefile build.
- Install MinGW
- Install gcc-arm
- Optional but recommended: install git, git-shell etc.
You will have to make modifications to the Makefile in order to tell make where the tools are installed:
- edit mcHF Makefile like this:
#PREFIX = /usr
PREFIX = „path to gccarm“ (like c:/programs/gccarm)
and
clean:
# $(RM) $(call FixPath,$(OBJS))
# $(RM) $(call FixPath,$(LPRJ).elf)
# $(RM) $(call FixPath,$(PRJ).bin)
# $(RM) $(call FixPath,$(LPRJ).map)
# $(RM) $(call FixPath,*~)
$(RM) $(OBJS)
$(RM) $(LPRJ).elf
$(RM) $(PRJ).bin
$(RM) $(LPRJ).map
$(RM) *~
After that it performs the same way as on Linux.
Since Windows 10 "Anniversary Update", Bash on Ubuntu on Windows provides developers with a familiar Bash shell and Linux environment in which you can run most Linux command-line tools, directly on Windows, UNMODIFIED, without needing an entire Linux virtual machine. This is very similar to MinGW with the advantage of a full access to the Ubuntu and Debian software library.
First, install Bash on Ubuntu on Windows with the help of the Installation Guide. You will get Ubuntu 14.04 (trusty) on Windows 10 Anniversary Update (version 1607) or Ubuntu 16.04 (xenial) on Windows 10 Creator Update(version 1703).
Next, install the development tools:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential
sudo apt-get install python-minimal
On Creator Update, install the cross compiler:
sudo apt-get install gcc-arm-none-eabi
On Anniversary Update, install the cross compiler as on Debian Jessie above.
Finally, get the source files and compile:
cd
git clone https://github.com/df8oe/mchf-github.git
cd mchf-github/mchf-eclipse
make all
Following the complete instructions on the GNU ARM Eclipse pages for installing will give you a nice working setup including nice debugging capabilities. It might seem like a lot of instructions and you have to jump between pages, but this is well-spent effort, especially on Windows.
Do not forget to install the packs for the STM32F4 processor. Detailed instructions for this step may appear here in future.
See the instructions in the mchf-embitz project folder of the repository
CoIDE is a all-in-one IDE for ARM processors on Windows. It is simpler to use than Eclipse but also less extensible.
The GitHub project contains a working CoIDE 1.7.x project. Download CoIDE 1.7.8. In addition you will need only a GCC ARM Tool Chain. Follow the instructions given above to install one.
DO NOT USE CoIDE 2.0 or newer. Build fails on these. There are no plans to migrate the CoIDE project to 2.0, however, if you made a successful migration, let us know and we may be able to integrate that. Otherwise, stick to CoIDE 1.7.8.
- Get yourself a ST-LINK V2 compatible USB stick. These sell for 8-15USD/EUR/GBP on Amazon
- Update to newest stick to newest ST LINK V2 firmware. This solves some issues.
- Solder a 4 pin strip 90 degrees to connector P8
- Solder another pin from a pin strip to a place where you can get a ground connection (or clip a wire to the casing of one of the USB sockets)
- Connect SWDIO,SWCLK,NRST to the respective pins on P8. Connect ground pin from stick to mcHF. At this point latest the mcHF will go into reset.
- To connect the original ST-LINK/V2 you have to connect pin 1 from 20 pin header from ST-LINK to UI_3V_MCU on UI board. E.g. you can use one of P6 pins. If you use a "clone" ST-LINK/V2 stick, you do not have to connect 3.3V
- One of the verified configurations in ST-LINK Utility - Mode: Hot Plug, Reset Mode: Hardware Reset, Frequency: 1,8MHz
- Use a SHORT cable to connect ST-LINK and mcHF. Less than 10cm is recommended. All sort of sporadic errors happen with longer cables. You have been warned.
There are many other hardware interfaces on the market for debugging ARM processors. If you buy one of these and get to work, just document it here. In other words: Not yet supported.
No, not for compiling and debugging. But for contributing, getting up-to-date source code easily, collaborating, .... That's way we recommend strongly to have both.
cd mchf-eclipse
make all
will produce, if successful, the file firmware mchf.bin in this directory. make clean will remove all generated files.
cd mchf-eclipse/bootloader/src
make
will compile the bootloader code.
If it fails, make sure that all the required tools are in the execution path.
First see MinGW install information above. Then run it just like on Linux.
make clean
make all
-
Import project using "File->Import->General->Existing Project".
-
Make sure to be in the "C/C++" perspective. This is visible in the window title bar (you will see "C/C++" as part of the window title. If not, "Window"->"Perspective"->"Open Perspective"->"C/C++" oder ... "Other"->"C/C++" will get you there.
-
Select "DebugLib" build configuration using "Project"->"Build Configurations"->"Set Active"->"DebugLib"
-
Run "Project->Build". Build uses make just like a command line build.
-
Select "Debug" build configuration using "Project"->"Build Configurations"->"Set Active"->"DebugLib"
-
Run "Project->Build". Build uses make just like a command line build.
-
Resulting firmware file (mchf-eclipse.bin) is in directory "Debug".
Now you can change the code and run "Project->Build".
The bootloader can be build by selecting "DebugBoootloader" and can be found in "DebugBootloader".
See the instructions in the mchf-embitz project folder of the repository
- Start IDE, open project using file
firmware.coproj. - Run "Project->Build Project".
- Resulting firmware file is placed by default in firmware_target/Debug
There are different ways how to get the newly built binary on the mcHF. While the first two alternatives work, the third choice which uses a USB dongle, is the quickest way to do it and the only one which gives you also full debugging support in real-time.
- Make sure you have the DF8OE bootloader (the one which is built from the sources in this project) installed on your machine.
- Put the file
mchf.binon a supported USB stick, connect stick using OTG cable to mini-USB socket of mcHF - Boot with the button BAND- pressed.
- Make sure you have the M0NKA bootloader (the one which can be downloaded from M0NKA mcHF pages installed on your machine.
- Boot with the button BAND- pressed. Red and green led should flash alternatively
- Now connect mcHF mini USB port with PC. Install mcHF Manager driver manually for the now appearing device.
- Connect stick to PC, use either direct connection or good cables/hubs. Bad USB extension cables caused problems during flashing.
- Now put your finger on the Power button and do not release it. If your machine shuts down completely at this point, you have to supply permanently power (3.3V to the MCU).
- CoIDE:
- Just press the "Flash" button. This will start first the flashing and then start the mcHF.
- Eclipse:
- Make sure you have the right run configuration selected.
- Just press the "Run" button. This will start first the flashing then start the mcHF.
- Command Line:
- Start openocd with
openocd -f support/MCHF.cfg. This should produce some output and mention the successful connection to the target MCU. - Start gdb with
gdb mchf.elf. Yes,mchf.elfnotmchf.bin - TBD
- Start openocd with
The easiest way to debug the mcHF Software is to run the mcHF connected to a PC via ST LINK V2 USB Adapter and Eclipse installed as described before. This offers starting and stopping the mcHF, reading the memory, variables, setting breakpoints easily in the code editor and so on. You can even use special calls (trace_printf/trace_write) which will insert debug output in the code. The output is shown on the PC (data is sent via the debug interface, no extra connection required).
Similar functionality is available on the command line, with gdb and openocd.
In a nutshell, if you can flash the mchf using Eclipse or gdb/openocd, you can also run debug using the same interface.
By default the debug output via semihosting is disabled. Two reasons for that: It takes resources and even more importantly, if enabled, it produces binaries which do not work without the ST LINK debugger active! Only activate this in your local builds.
In order to have semihosting working, you need to add two defines to your build system:
- OS_USE_TRACE_SEMIHOSTING_STDOUT
- TRACE
In Eclipse, you can select the Build Configuration "DebugSemihosting", which has these defines set.
We added support for profiling the mcHF software (sort of). It helps you to count how often something happens and/or how long something takes at the granularity of single CPU clock cycle, which is 5,9nS (yes, nanoseconds).
You have to include "profiling.h" in the source file of interest, define a new profiling event in ProfiledEventNames (or reuse an existing one, if it is not in use, check carefully).
Profiling will be disabled by default. If "PROFILE_EVENTS" is defined, it is active.
Call profileEvent(EventName). This will increment the counter of the event in the eventProfile datastructure. Access the data there via "eventProfile[EventName].count". You may use the trace print functionality to print out the counter or you simply use the debugger to inspect the value in memory.
This is a little more complex.
- First start the cycle timer with "profileTimeEventInit()" .This resets the timer and makes it run.
- At any time call profileTimedEventStart(EventName) to have the start being recorded. At the end of the event call profileTimedEventStop(EventName)
The duration of a single event should not be longer then 2^32 / clock frequency, i.e. ~25s @168 Mhz for a single event. Total duration recorded should not be more than 2^64 cycles which is quite a lot, i.e. there is no limit on that for the average person in this universe.
Due to the approach multiple events can be recorded simultaneously correctly but outer events include the overhead of the calculation of the duration of the inner ones. Only the innermost events are more or less accurate. In many cases this deficit is neglectable since the measurement has very low overhead.
The recorded data is the time in cycles of the all active periods of that event. There is also a counter, so that it is possible to calculate the average event duration: "eventProfile[].duration/eventProfile[EventName].count"
- Supported SDR Hardware
- UHSDR: Manuals
- mcHF: Building your own SDR
- OVI40: Building your own SDR
- UHSDR: SW Installation on SDR
- UHSDR: Theory of Operation
- UHSDR: SW Development
- UHSDR: Supported Hardware
- UHSDR: Manuals
- Building a mcHF SDR
-
Building a OVI40 SDR
- UHSDR SW Installation
- Theory of Operation
- UHSDR SW Development