Windows Quick Start: Difference between revisions

From Miosix Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=== Before you begin ===
=== Before you begin ===


Before you can install the Miosix Toolchain on Windows, you will need to install [[https://en.wikipedia.org/wiki/Git_%28software%29 git]], which is necessary to download the Miosix kernel and keep it up to date, [[https://en.wikipedia.org/wiki/Perl Perl]], which is a scripting language used when compiling the kernel, and the STLink drivers if you want to program stm32 boards that have an USB-based STLinkV2 programmer/debugger.
Before you can install the Miosix Toolchain on Windows, you will need to install [https://en.wikipedia.org/wiki/Git_%28software%29 git], which is necessary to download the Miosix kernel and keep it up to date, [https://en.wikipedia.org/wiki/Perl Perl], which is a scripting language used when compiling the kernel, and the STLink drivers if you want to program stm32 boards that have an USB-based STLinkV2 programmer/debugger.


* For git, it is recomended to install it from [[http://www.git-scm.com/download/win git-scm.com]]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.
* For git, it is recomended to install it from [http://www.git-scm.com/download/win git-scm.com]. Please '''do not''' uncheck the ''Windows Explorer integration'' feature during the installation, as you will need it to install the kernel sources.
* [[http://strawberryperl.com Strawberry perl]] is the recomended perl version for Miosix on Windows
* [http://strawberryperl.com Strawberry perl] is the recomended perl version for Miosix on Windows
* The STLink drivers can be found on the [[http://www.st.com/web/en/catalog/tools/PF258168# ST website]].
* The STLink drivers can be found on the [http://www.st.com/web/en/catalog/tools/PF258168# ST website].


Finally, it is recomended to download a better text editor than Notepad or WordPad, as you will need it to edit the Miosix configuration files. [[http://www.notepad-plus-plus.org/ Notepad++]] is a good option, but many other options exist. Just '''don't use notepad''', because it does not recognize Unix [[https://en.wikipedia.org/wiki/Line_ending line-endings]] and will show you Miosix source files as if they were composed of a single line of text.
Finally, it is recomended to download a better text editor than Notepad or WordPad, as you will need it to edit the Miosix configuration files. [http://www.notepad-plus-plus.org/ Notepad++] is a good option, but many other options exist. Just '''don't use notepad''', because it does not recognize Unix [https://en.wikipedia.org/wiki/Line_ending line-endings] and will show you Miosix source files as if they were composed of a single line of text.


Once you have downloaded and installed the aforementioned software, you can proceed with the installation of the Miosix Toolchain.
Once you have downloaded and installed the aforementioned software, you can proceed with the installation of the Miosix Toolchain.
Line 13: Line 13:
=== Install the Miosix Toolchain ===
=== Install the Miosix Toolchain ===


Download the [[http://miosix.org/toolchain/MiosixToolchainInstaller.exe Miosix Toolchain installer]] and run it. At the end you will need to reboot your computer (sorry, it's Windows...)
Download the [[Miosix Toolchain]] and run it. At the end you will need to reboot your computer (sorry, it's Windows...)


=== Get the Miosix kernel sources ===
=== Get the Miosix kernel sources ===
Line 21: Line 21:
[[File:Gitbashwindows.png]]
[[File:Gitbashwindows.png]]


Currently, Miosix 2.0 is in the ''testing'' branch of the git repository, while the default one, the ''master'' branch, contains Miosix 1.x. So, you need to explicitly switch to the testing branch after downloading the kernel. To do so, type the following commands in the git shell.
The Miosix git repository used to be hosted at [http://gitorious.org gitorious.org], but the service was shut down. For this reason, the kernel is now hosted directly at miosix.org. There is also a [https://github.com/fedetft/miosix-kernel github mirror] and the two repositories will be always kept in sync. Currently, the ''master'' branch contains the stable 2.0 kernel, while the ''testing'' branch contains the current development version. Kernel versions prior to 2.0 are deprecated.


<source lang="bash">
<source lang="bash">
git clone https://git.gitorious.org/miosix-kernel/miosix-kernel.git
git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
cd miosix-kernel
git fetch origin
git fetch origin
git checkout -b testing origin/testing
## To select the development version of the kernel
#git checkout -b testing origin/testing
exit
exit
</source>
</source>
Line 37: Line 38:
=== Configuring and compiling the kernel ===
=== Configuring and compiling the kernel ===


More in-depth information on how th configure the kernel for your board can be found in the [[Board List]], but for now we will assume you have an stm32f4discovery, which is a common board, and briefly show how to get to a blinking LED example.
More in-depth information on how th configure the kernel for your board can be found in the [[Board list]], but for now we will assume you have an stm32f4discovery, which is a common board, and briefly show how to get to a blinking LED example.


'''Top-level directory'''
'''Top-level directory'''
Line 70: Line 71:
#OPT_BOARD := stm32f205rg_sony-newman
#OPT_BOARD := stm32f205rg_sony-newman
</source>
</source>
In Makefile syntax a '#' sign denotes a comment, so to select a board you have to comment out (by prepending a '#') the default board selected, and uncomment (by removing the '#' at the start of the line) your board, in this case, which in this example will assume is the ''stm32f407vg_stm32f4discovery''.
In Makefile syntax a '#' sign denotes a comment, so to select a board you have to comment out (by prepending a '#') the default board selected, and uncomment (by removing the '#' at the start of the line) your board, which in this example is the ''stm32f407vg_stm32f4discovery''.


Next, edit the ''miosix_settings.h'' using Notepad++ and uncomment (by removing the '//' at the start of the line) the following line
Next, edit the ''miosix_settings.h'' file using Notepad++ and uncomment (by removing the '//' at the start of the line) the following line
<source lang="CPP">
<source lang="CPP">
//#define JTAG_DISABLE_SLEEP
//#define JTAG_DISABLE_SLEEP
</source>
</source>
(which is towards the end of the file). This is a C++ header file, so the comment syntax is '//'. More information on the meaning of this line can be found in [[miosix_settings.h]], but a short summary is that this line prevents the kernel from putting shutting down the CPU when it has nothing to do, which saves power but interferes with the programming/debugging protocol used to program the board via QSTLink2.
(which is towards the end of the file). This is a C++ header file, so the comment syntax is '//'. More information on the meaning of this line can be found in [[miosix_settings.h]], but a short summary is that this line prevents the kernel from shutting down the CPU when it has nothing to do, which saves power but interferes with the programming/debugging protocol used to program the board via QSTLink2.
 
Also, comment out the ''#error'' line towards the beginning of the file. This line exists to cause a compilation error if the user forgets to edit the ''miosix_settings.h'' file. The result should look like this:
<source lang="CPP">
// Before you can compile the kernel you have to configure it by editing this
// file. After that, comment out this line to disable the reminder error.
// The PARSING_FROM_IDE is because Netbeans gets confused by this, it is never
// defined when compiling the code.
#ifndef PARSING_FROM_IDE
//#error This error is a reminder that you have not edited miosix_settings.h yet.
#endif //PARSING_FROM_IDE
</source>


'''Blink a LED'''
'''Blink a LED'''
Line 119: Line 131:
[[File:Qstlink2flashingwindows.png]]
[[File:Qstlink2flashingwindows.png]]


Note that, regardless of using QSTLink2 form the DOS prompt or the GUI, there is a bug that in some circumstances blocks the microcontroller until the next powercycle. Therefore, after having programmed the microcontroller, is is recomended to unplug and reconnect the USB cable to powercycle the ''stm32f4discovery'' board. At that point, you shuold see the red LED blinking.
Note that, regardless of using QSTLink2 form the DOS prompt or the GUI, there is a bug that in some circumstances blocks the microcontroller until the next powercycle. Therefore, after having programmed the microcontroller, it is recomended to unplug and reconnect the USB cable to powercycle the ''stm32f4discovery'' board. At that point, you shuold see the red LED blinking.
 
Lastly, if you have a brand new board and QSTlink doesn't work you may take a look at [[ST-LINK utility update|this page]].


=== What's next? ===
=== What's next? ===
Line 128: Line 142:


To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that Git, Perl and the STLink drivers have their own uninstallers. Also, the ''miosix-kernel'' in the ''Documents'' directory will not be removed.
To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under ''Miosix Toolchain''. Note that Git, Perl and the STLink drivers have their own uninstallers. Also, the ''miosix-kernel'' in the ''Documents'' directory will not be removed.
[[Category:Installation and Configuration]]

Latest revision as of 08:48, 16 December 2016

Before you begin

Before you can install the Miosix Toolchain on Windows, you will need to install git, which is necessary to download the Miosix kernel and keep it up to date, Perl, which is a scripting language used when compiling the kernel, and the STLink drivers if you want to program stm32 boards that have an USB-based STLinkV2 programmer/debugger.

  • For git, it is recomended to install it from git-scm.com. Please do not uncheck the Windows Explorer integration feature during the installation, as you will need it to install the kernel sources.
  • Strawberry perl is the recomended perl version for Miosix on Windows
  • The STLink drivers can be found on the ST website.

Finally, it is recomended to download a better text editor than Notepad or WordPad, as you will need it to edit the Miosix configuration files. Notepad++ is a good option, but many other options exist. Just don't use notepad, because it does not recognize Unix line-endings and will show you Miosix source files as if they were composed of a single line of text.

Once you have downloaded and installed the aforementioned software, you can proceed with the installation of the Miosix Toolchain.

Install the Miosix Toolchain

Download the Miosix Toolchain and run it. At the end you will need to reboot your computer (sorry, it's Windows...)

Get the Miosix kernel sources

Go to the directory where you want to dowload the Miosix kernel, for example the Documents directory, and right-click on it. Select Git bash to open a git shell. There you can type the commands to download the kernel.

Gitbashwindows.png

The Miosix git repository used to be hosted at gitorious.org, but the service was shut down. For this reason, the kernel is now hosted directly at miosix.org. There is also a github mirror and the two repositories will be always kept in sync. Currently, the master branch contains the stable 2.0 kernel, while the testing branch contains the current development version. Kernel versions prior to 2.0 are deprecated.

git clone https://miosix.org/git-public/miosix-kernel.git
cd miosix-kernel
git fetch origin
## To select the development version of the kernel
#git checkout -b testing origin/testing
exit

Note that it is possible to paste commands in the shell (so as to avoid typing them, which can be tedious and lead to typos), but you have to do it one line of text at a time, and to paste you need to use the Shift+Ins shortcut, not the usual Ctrl+v one. The last command, exit, will close the shell.

Note that there is also a 'Git GUI' in the right click menu, but since I don't know how to use it, you're on your own if you choose that route.

Configuring and compiling the kernel

More in-depth information on how th configure the kernel for your board can be found in the Board list, but for now we will assume you have an stm32f4discovery, which is a common board, and briefly show how to get to a blinking LED example.

Top-level directory

First of all the miosix-kernel directory is often referred to as the top-level directory of the kernel. It contains, among other, the main.cpp file which is where you can start writing your application code, the Makefile where you can add additional C++ and C source files to be compiled, and the miosix directory which contains the kernel.

Miosixtopleveldirectorywindows.png

All paths in this wiki, unless they start with a '/' (for Linux) or 'C:\' (For Windows), are intended relative to Miosix's top-level directory, so if we're talking about the 'miosix/config/Makefile.inc' file you can find it within the directory where you have downloaded the kernel from git.

Configuring the kernel

The kernel is configured by editing two files, named miosix/config/Makefile.inc and miosix/config/miosix_settings.h. Open the first one in Notepad++, and select your board. To do so, look for the OPT_BOARD section of the file, which looks like this:

##
## Target board, choose one. This also implicitly select the target
## architecture
##
#OPT_BOARD := lpc2138_miosix_board
OPT_BOARD := stm32f103ze_stm3210e-eval
#OPT_BOARD := stm32f103ve_mp3v2
#OPT_BOARD := stm32f100rb_stm32vldiscovery
#OPT_BOARD := stm32f103ve_strive_mini
#OPT_BOARD := stm32f103ze_redbull_v2
#OPT_BOARD := stm32f407vg_stm32f4discovery
#OPT_BOARD := stm32f207ig_stm3220g-eval
#OPT_BOARD := stm32f207zg_ethboard_v2
#OPT_BOARD := stm32f207ze_als_camboard
#OPT_BOARD := stm32l151_als_mainboard
#OPT_BOARD := stm32f407vg_bitsboard
#OPT_BOARD := stm32f205rg_sony-newman

In Makefile syntax a '#' sign denotes a comment, so to select a board you have to comment out (by prepending a '#') the default board selected, and uncomment (by removing the '#' at the start of the line) your board, which in this example is the stm32f407vg_stm32f4discovery.

Next, edit the miosix_settings.h file using Notepad++ and uncomment (by removing the '//' at the start of the line) the following line

//#define JTAG_DISABLE_SLEEP

(which is towards the end of the file). This is a C++ header file, so the comment syntax is '//'. More information on the meaning of this line can be found in miosix_settings.h, but a short summary is that this line prevents the kernel from shutting down the CPU when it has nothing to do, which saves power but interferes with the programming/debugging protocol used to program the board via QSTLink2.

Also, comment out the #error line towards the beginning of the file. This line exists to cause a compilation error if the user forgets to edit the miosix_settings.h file. The result should look like this:

// Before you can compile the kernel you have to configure it by editing this
// file. After that, comment out this line to disable the reminder error.
// The PARSING_FROM_IDE is because Netbeans gets confused by this, it is never
// defined when compiling the code.
#ifndef PARSING_FROM_IDE
//#error This error is a reminder that you have not edited miosix_settings.h yet.
#endif //PARSING_FROM_IDE

Blink a LED

Open the main.cpp file in the top-level directory using Notepad++, and replace its content with the following program:

#include <miosix.h>
using namespace miosix;
int main()
{
    for(;;)
    {
        ledOn();
        Thread::sleep(1000);
        ledOff();
        Thread::sleep(1000);
    }
}

The Miosix board support package defines the ledOn() and ledOff() functions to control a LED on the board for all the boards that have at least one software-accessible LED.

Compiling

To compile the kernel, open a DOS shell in the Miosix top-level directory (you can 'Shift+Right click' in the top-level directory and choose 'Open command window here' in modern versions of Windows), otherwise you will have to cd your way into that directory.

Openterminalwindows.png

To compile the kernel type make in the DOS prompt. If all goes well, the result should look like this.

Makeoutputwindows.png

Otherwise, compiler errors will appear in the DOS prompt. The number that appears under text in the make output is the size in bytes of your application plus the kernel. If you think that 90KBytes is a bit too much for a blinking led, don't worry. The kernel by default includes support for C stdio functions, filesystem code including Unicode support and the C++ exception handling runtime, all of which can be disabled to significantly reduce code size.

Programming

There are two ways to program the stm32f4discovery board. One is to use QSTLink2 directly from the DOS prompt you already have open by typing 'make program' (connect the USB cable first!), the other is through QSTLink2's GUI. You can find QSTLink2 in the start menu

Qstlink2startmenuwindows.png

Once you start it, you have to click on Connect, and it should find your stm32f4discovery board. After that, click on Send and select the main.bin file in the Miosix top-level directory.

Qstlink2flashingwindows.png

Note that, regardless of using QSTLink2 form the DOS prompt or the GUI, there is a bug that in some circumstances blocks the microcontroller until the next powercycle. Therefore, after having programmed the microcontroller, it is recomended to unplug and reconnect the USB cable to powercycle the stm32f4discovery board. At that point, you shuold see the red LED blinking.

Lastly, if you have a brand new board and QSTlink doesn't work you may take a look at this page.

What's next?

You have finished the installation of the Miosix Toolchain. You may want to install and configure an IDE, or the debugger.

Uninstall the Miosix Toolchain

To uninstall the Miosix Toolchain, you can find the uninstaller in the start menu under Miosix Toolchain. Note that Git, Perl and the STLink drivers have their own uninstallers. Also, the miosix-kernel in the Documents directory will not be removed.