Miosix Wiki - User contributions [en]

Linux Debugger configuration

2016-06-26T10:26:30Z

Andreabont:

The debugging of Miosix on Linux can be done through [http://openocd.net/ OpenOCD], that creates a bridge between GDB and the JTAG device.

== Setting up OpenOCD ==

=== Install OpenOCD ===
<source lang="bash">
sudo apt-get install openocd # Install OpenOCD for Ubuntu/Debian
</source>

=== Run OpenOCD ===
The OpenOCD configuration is included in the official Miosix distribution under the path 'miosix/arch'. You must choose the proper config file for the device in use. For example for the stm32f429zi_stm32f4discovery board:
<source lang="bash">
openocd -f miosix/arch/cortexM4_stm32f4/stm32f429zi_stm32f4discovery/stm32f4discovery.cfg
</source>

== Debugging with GDB ==
The GDB used is provided by the official [[Miosix_Toolchain|Miosix Toolchain]]. If you haven't already installed it's time to do it. The debugger must be launched on the ELF binary file.
<source lang="bash">
arm-miosix-eabi-gdb main.elf
</source>

=== Connect GDB ===
OpenOCD provide a network interface for connect the debugger, the follow command is necessary for establish the connection:
<source lang="bash">
(gdb) target remote <ip>:<port>
</source>

The default socket is listening on port 3333 in the loopback interface of your computer. So you can use the default command:
<source lang="bash">
(gdb) target remote :3333
</source>

=== Reset the board ===
After the connection (and after each change of configuration) you must reset the board in a safe state:
<source lang="bash">
(gdb) monitor reset halt
</source>

=== Flash a new firmware ===
If you want to upload to the board a new firmware version you can made it through gdb and OpenOCD, you must indicate the binary file and the address of the flash memory of your board:
<source lang="bash">
(gdb) monitor flash write_image erase main.bin 0x08000000
</source>
It's often necessary to perform a reset of the board before and after the firmware upload.

[[Category:Installation and Configuration]]

Linux Debugger configuration

2016-06-26T10:16:58Z

Andreabont: Created page with "The debugging of Miosix on Linux can be done through [http://openocd.net/ OpenOCD], that creates a bridge between GDB and the JTAG device. == Setting up OpenOCD == === Insta..."

Board list

2015-01-22T20:23:45Z

Andreabont: Add link

This page lists the vaious boards that Miosix supports. The board naming convention used in this list is the same as the one used in [[Makefile.inc|miosix/config/Makefile.inc]], with the name of the microcontroller followed by the board name.

{| class="wikitable"
|-
! Name !! Description !! Links
|-
| [[lpc2138_miosix_board]] || Official Miosix board || [https://miosix.org/boards/miosix_board-overview.html Overview]
|-
| [[stm32f103ze_stm3210e-eval]] || || [http://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/CD00178166.pdf User Manual]
|-
| [[stm32f103ve_mp3v2]] || ||
|-
| [[stm32f100rb_stm32vldiscovery]] || The small discovery board with a 24MHz CPU || [http://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/CD00267113.pdf User Manual]
|-
| [[stm32f103ve_strive_mini]] || ||
|-
| [[stm32f103ze_redbull_v2]] || ||
|-
| [[stm32f407vg_stm32f4discovery]] || The discovery board with an audio connector and a 168MHz CPU || [http://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/DM00039084.pdf User Manual]
|-
| [[stm32f207ig_stm3220g-eval]] || || [http://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/DM00022972.pdf User Manual]
|-
| [[stm32f207zg_ethboard_v2]] || ||
|-
| [[stm32f207ze_als_camboard]] || ||
|-
| [[stm32l151_als_mainboard]] || ||
|-
| [[stm32f407vg_bitsboard]] || ||
|-
| [[stm32f205rg_sony-newman]] || A smart watch made by Sony, with an OLED display ||
|-
| [[stm32f429zi_stm32f4discovery]] || The new discovery board with a touchscreen display and 8MB of external RAM || [http://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/DM00093903.pdf User Manual]
|}

[[Category:Boards]]

Board list

2015-01-22T20:20:28Z

Andreabont: Format with table and add links

Stm32f407vg stm32f4discovery

2015-01-22T20:06:53Z

Andreabont: Adding category

;STM32F4DISCOVERY
* A [http://www.st.com/web/catalog/tools/PF252419 discovery board] for [http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN11/PF252140 STM32F407VGT6] microcontroller with 168 MHz [[ARM Cortex-M4F]] core, 1024 KB Flash, 192 KB RAM, 4 KB battery-backed RAM in [[LQFP]]100 package.
* This board includes an integrated [http://www.st.com/web/catalog/tools/PF219866 ST-LINK/V2] debugger via [[Mini-USB|Mini-B USB]] connector, [[accelerometer]] (LIS302DL), [[microphone]] (MP45DT02), audio [[codec]] (CS43L22), [[Phone connector (audio)|3.5 mm audio jack]], 4 user LEDs, user button, reset button, Full-Speed [[USB On-The-Go|USB OTG]] to second [[MicroUSB|Micro-AB USB]] connector, and two 25x2 male [[pin header]]s.
* A separate [http://www.farnell.com/datasheets/1671410.pdf STM32F4DIS-BB] baseboard is available.

=== Configuring the kernel ===
Unlike the stm32vldiscovery, this board has the STLink/V2 firmware which is much more Linux friendly. All you need is a recent version of OpenOCD and the [https://github.com/fpoussin/QStlink2 QStlink2] tool to support ths board.

First, make sure the correct board is selected in the '''miosix/config/[http://gitorious.org/miosix-kernel/miosix-kernel/blobs/master/miosix/config/Makefile.inc Makefile.inc]''' file.
The line defining the OPT_BOARD variable should be set to '''OPT_BOARD := stm32f407vg_stm32f4discovery''', that is, that line should be uncommented, and the other commented out, like this:

<source lang="CPP">
##
## 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
</source>
In addition, this board has a couple of board-specific options in the Makefile.inc file. For convenience, the relevant part of that configuration file is reported here so as to be easily located within the file

<source lang="CPP">
##---------------------------------------------------------------------------
## stm32f407vg_stm32f4discovery
##
ifeq ($(OPT_BOARD),stm32f407vg_stm32f4discovery)

## Linker script type, there are two options
## 1) Code in FLASH, stack + heap in internal RAM (file *_rom.ld)
## 2) Code + stack + heap in internal RAM (file *_ram.ld)
LINKER_SCRIPT_PATH := arch/cortexM4_stm32f4/stm32f407vg_stm32f4discovery/
LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+192k_rom.ld
#LINKER_SCRIPT := $(LINKER_SCRIPT_PATH)stm32_1m+192k_ram.ld

## This causes the interrupt vector table to be relocated in SRAM, must be
## uncommented when using the ram linker script
#SRAM_BOOT := -DVECT_TAB_SRAM

endif
</source>

As can be seen, the file is made mostly of comments, and defines three options: '''LINKER_SCRIPT''' and '''SRAM_BOOT'''. The comments explain in detail the meaning of there options, so it isn't necessary to further explain them.

Then you should disable filesystem support. Since this board lacks a microSD card or other hardware that could support a filesystem, the bsp has no filesystem backend implementation and if you leave the filesystem enabled the kernel will fail to compile saying it can't find a backend.
To do so, open the '''miosix/config/[http://gitorious.org/miosix-kernel/miosix-kernel/blobs/master/miosix/config/miosix_settings.h miosix_settings.h]''' and comment out the

#define WITH_FILESYSTEM

After modifying configuration files it is recomended to do a '''make clean; make''' (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

=== Loading code ===
As explained before, there are more than one linker script for this board, and the selected linker script affects the way code should be loaded on the board.
*The stm32_1m+192k_rom.ld is the '''default linker script''', and put the code in FLASH, so you need to program the microcontroller's FLASH every time you change your code, but code will run faster and won't be lost at each reboot. A simple way to load code in FLASH is to use the [[QStlink2]] tool.
*The stm32_1m+192k_ram.ld linker script is very useful for debugging code on this board, as it locates everything (code, stack, heap) in the microcontroller's RAM. It has the disadvantage that the loaded code is lost upon reboot (being in a volatile memory), but for debugging,it is not an issue.

=== stdout redirection ===

The board support package of this board is a little different from the other, as by default it will redirect stdout (but not stdin!) through the '''debug communication channel'''. This means that if you are debugging your board with OpenOCD+gdb, you'll see the output of printf directly in your gdb shell. Since the debug communication channel is unidirectional, stdin is redirected nowhere, and attempting to read from it will result in an infinte loop.
This has been done to keep the board "self contained", that is, to be able to write and test code without adding additional hardware.

If on the other hand, you have a 3.3V logic level USB to serial adapter, such as one based on the FT232 chip, you can still redirect printf to the serial port USART3 (GPIO PB10 and PB11 on the board). This also has the advantage of making both stdout and stdin work.
To do so, edit the file '''miosix/arch/cortexM4_stm32f4/stm32f407vg_stm32f4discovery/[https://gitorious.org/miosix-kernel/miosix-kernel/blobs/master/miosix/arch/cortexM4_stm32f4/stm32f407vg_stm32f4discovery/board_settings.h board_settings.h]''' and comment out the line #define STDOUT_REDIRECTED_TO_DCC

=== In Circuit Debugging ===
Before you begin you should note that the Miosix kernel will put the CPU to a '''low power state''' when no thread is running. This low power state will usually confuse debuggers and make them lose sync with the CPU. To avoid this you need to edit the '''miosix/config/[http://gitorious.org/miosix-kernel/miosix-kernel/blobs/master/miosix/config/miosix_settings.h miosix_settings.h]''' file and uncomment
#define JTAG_DISABLE_SLEEP
This will prevent the kernel from putting the CPU in its low power state making debugging possible.
Also, to be able to precisely single-step your code you need to '''disable compiler optimizations''' as gdb is incapable of reliably debug an optimized code. The option is in the miosix/config/Makefile.inc file and is the OPT_OPTIMIZATION := -O0 that should be uncommented while the other lines related to the same option should be commented out.

After modifying configuration files it is recomended to do a '''make clean; make''' (or in the Netbeans IDE, to click on the "Clean and build project" button) to be sure that changes are applied.

Since the board has an on board SWD in circuit debugger, simply '''plugging the USB cable''' is all you need from an hardware point of view.
On the software side, you need to '''open two shells'''. In one do a

sudo openocd -f miosix/arch/cortexM4_stm32f4/stm32f407vg_stm32f4discovery/stm32f4discovery.cfgg

This will '''start the OpenOCD''' program that will connect to the board and listen for GDB connections.

In the second shell type the following commands

arm-miosix-eabi-gdb main.elf
target remote :3333
monitor soft_reset_halt
monitor target_request debugmsgs enable
monitor trace point 1
break main
continue

The first command will '''start the gdb debugger'''. The following commands are typed into the gdb console, and tell it to connect to OpenOCD, and reset the board, enable the debug communication channel to redirect printf, and stop the program at the beginning of main()
To load the program to be debugged, you can either do a make program before and then start debugging, or you can directly write the FLASH memory from within gdb with this command
monitor flash write_image erase main.bin 0x08000000
From there on, consult a gdb reference on the Internet for information on how to single step code, set breakpoints and inspect variables.

=== (Optional) Configuring the Netbeans IDE ===
To have a fully working code completion that can also resolve the board-specific symbols, right click on the project, go to Set Configuration and select the right board.
[[File: Netbeans-config.png]]

=== Miosix GPIO Mapping ===

==== SD Card ====
Connect VCC (3V) and GND using a 100nF capacitor between VCC and GND, this will be useful to overcome to current absorption peaks.

{| class="wikitable"
|-
! SD !! STM32 !! Optional
|-
| CLK || PC12 ||
|-
| CMD || PD2 ||
|-
| D0 || PC8 ||
|-
| D1 || PC9 || Y
|-
| D2 || PD10 || Y
|-
| D3 || PC11 || Y
|}

Each connection needs a pullup resistor between ~47Kohm and 100Kohm.

Optional GPIOs are used in 4-bit mode.

=== Resource ===
stm32f4discovery [http://www.st.com/st-web-ui/static/active/en/resource/technical/document/user_manual/DM00039084.pdf Datasheet]

[[Category:Boards]]

Category:Optimization

2015-01-22T20:05:25Z

Andreabont: Create Category

Optimization

Miosix code size optimization

2015-01-22T20:04:57Z

Andreabont: Adding Categories

Miosix is designed with the end goal to become an "unix on a chip" written in C++, so it was built with the idea of packing as much standard compliance as possible, without cutting corners. Things like full support to the C and C++ standard libraries, including full support for the C++ STL, thread-safe exception handling, and seldom used features of the C standard libraries, including stdout redirection via
<source lang="CPP">
fclose(stdout);
stdout=fopen("/sd/log.txt","w");
puts("writing to a file\n");
fflush(stdout);
</source>
are supported. This obviously comes with a code size penalty, especially considering that most features are enabled by default.
However, the kernel is very modular, so you don't have to pay the code size cost of unused features in your application.

This guide lists a number of tips to adapt the Miosix kernel to the needs of code-size constrained embedded applications. The exact figures presented here may change as the kernel is developed further, but the tips are expected to remain valid. Considering the [[stm32f407vg_stm32f4discovery]] which is a common board used with Miosix, compiling an empty ''main()'' with the default settings leads to a code size of over 90KB. With this guide it is possible to reduce code size down to 6KB by removing various features you may not need.

== Compile with Os ==

The default [http://fedetft.wordpress.com/2009/10/01/gcc-optimization-flags GCC optimization flag] used in Miosix is ''-O2'', which generates code optimized for speed. You can however choose ''-Os'' which optimizes for size by opening the file [[Makefile.inc|miosix/config/Makefile.inc]], commenting out the ''-O2'' line, and uncommenting the ''-Os'' line, like this:
<source lang="bash">
#OPT_OPTIMIZATION := -O0
#OPT_OPTIMIZATION := -O2
#OPT_OPTIMIZATION := -O3
OPT_OPTIMIZATION := -Os
</source>
The code size will usually decrease as a percentage of the total code size, as this option affects how the compiler generates code. 10% decrease is a common figure. Although I haven't found benchmarks showing how much this affects execution speed, usually the impact isn't that high, and code runs definitely much faster with respect to disabling optimizations altogether (with ''-O0''), so if you are tight on code size this is an easy option that does not require to sacrifice any feature of the kernel.

== Disable DevFs ==

Miosix 2.0 comes with an in-memory filesystem, mounted at ''/dev'' where device files can be addes, similarly to how a Linux machine works. The main purpose of this is to allow [[Miosix processes|processes]] to access peripherals, since due to memory protection they can't just access the peripheral registers. However, processes are currently disabled by default because they're still an experimental feature, so you can disable DevFs too. This can be done by commenting out the ''WITH_DEVFS'' line in [[miosix_settings.h|miosix/config/miosix_settings.h]], like this:

<source lang="CPP">
//#define WITH_DEVFS
</source>

This saves aroud 5KB.

== Disable the filesystem entirely ==

Miosix 2.0 has a completely rewritten filesystem subsystem, supporting multiple mountpoints, extensible filesystem types (currently Fat32 and DevFs), unicode UTF8 in file names, directory listing via the standard ''opendir()''/''readdir()''/''closedir()'' and more POSIX compilance, including inode emulation for Fat32. This comes at a code size cost, though. If your application does not need to read/write from files, you can disable the filesystem subsystem entirely. To do so, open [[miosix_settings.h|miosix/config/miosix_settings.h]] and comment out both the ''WITH_DEVFS'' and ''WITH_FILESYSTEM'' lines. When compared to the default when both filesystem and DevFs are enabled, about 40KB of code size can be saved.

== Use iprintf() instead of printf() in your application ==

''iprintf()'' is a non-standard extension of the [https://www.sourceware.org/newlib newlib] C library used by Miosix. It can do all what ''printf()'' can do except printing floating point numbers, and thath's why its code size is significantly lower, printing floating point numbers is quite complicated. Miosix already uses ''iprintf()'' internally, so to see the code size difference you have to write the following simple code in ''main()''

<source lang="CPP">
int main()
{
int i=0;
printf("%d\n",i);
//iprintf("%d\n",i);
}
</source>

Trying with ''iprintf()'' instead of ''printf()'', a 14KB code size reduction is observed. Note that you have to use a format string containing a % argument, such as %d to see the code size difference. If there is no % in the format string, GCC may replace ''printf()''/''iprintf()'' with a call to ''puts()'' as an optimization, and no code size difference can be seen.

== Disable boot logs ==

Maybe you're not using ''printf()'' at all in your application, however in this case you're still paying for the code size of ''iprintf()'' as the kernel uses it to print boot logs and error logs. To disable them, you can open [[miosix_settings.h|miosix/config/miosix_settings.h]] and uncomment ''WITH_BOOTLOG'' and ''WITH_ERRLOG''. This allows to save an additional 17KB of code size, but this is only true if there's no ''printf()'' call in your code, otherewise the code size saving will be minimal.

Also, keep in mind that error logs are a powerful tool to debug crashes of your application or the kernel during code development, so you may want to disable them only in release builds, and keep them enabled during development.

Finally, note that you can still access the serial port without using ''printf()'', by means of the POSIX calls ''write()'' and ''read()'', using ''STDOUT_FILENO'' and ''STDIN_FILENO'' as the ''fd'' argument.

== Disable the C++ exception runtime ==

The Miosix kernel is by default compiled with support for C++ exceptions, and unless you're also enabling [[Miosix processes|processes]] that depend on C++ exceptions, it is possible to disable their support. To di so, open [[Makefile.inc|miosix/config/Makefile.inc]] and uncomment the following line:

<source lang="bash">
OPT_EXCEPT := -fno-exceptions -fno-rtti -D__NO_EXCEPTIONS
</source>

This saves nearly 20KB but comes with quite an important side effect, though: if the heap is full, the kernel will reboot the machine. To explain why it is so, consider that the normal behaviour in Miosix to handle a full heap is that the C ''malloc()'' returns ''NULL'', while the C++ ''operator new'' throws an exception of type ''bad_alloc''. Now, when exceptions are disabled, ''new'' can no longer throw, but C++ code doesn't check for ''NULL'', as it expects an exception, and that would result in undefined behaviour. The only way to prevent undefined behaviour, is to reboot the machine, and that is what happens.

== Putting it all together ==

With all those tips presented so far applied simultaneously, the code size of an empty ''main()'' for the [[stm32f407vg_stm32f4discovery]] is reduced to around 10KB.

== One more thing, disable the serial port ==

The kernel, during the boot process, configures a serial port on nearly all the supported boards. If you really have no use for the serial port, you can disable it entirely, saving additional code size. To do so there is no configuration option, but you can edit the board support package file of your board. For the [[stm32f407vg_stm32f4discovery]] it's ''miosix/arch/cortexM4_stm32f4/stm32f407vg_stm32f4discovery/interfaces-impl/bsp.cpp'', and comment out the following lines in ''IRQbspInit()''

<source lang="CPP">
DefaultConsole::instance().IRQset(intrusive_ref_ptr<Device>(
new STM32Serial(defaultSerial,defaultSerialSpeed,
defaultSerialFlowctrl ? STM32Serial::RTSCTS : STM32Serial::NOFLOWCTRL)));
</source>

as well as the following line in ''shutdown()'' and ''reboot()''

<source lang="CPP">
DefaultConsole::instance().get()->ioctl(IOCTL_SYNC,0);
</source>

By applying also this last tip code size can be reduced to around 6KB.

[[Category:Installation and Configuration]]
[[Category:Optimization]]

Category:Libraries

2014-04-22T21:16:28Z

Andreabont:

Here a complete list of libraries: [[Library list]]

Library list

2014-04-22T21:16:02Z

Andreabont:

Libraries are additional components not part of the Miosix kernel that can be downloaded to add functionality to the kernel.

* [[mxgui]] is a GUI library for graphic displays
* [[mxusb]] is an USB stack, currently targeting stm32f1 microcontrollers only.

[[Category:Libraries]]

Library list

2014-04-22T21:15:32Z

Andreabont: Created page with "Category:Libraries"

[[Category:Libraries]]

Category:API

2014-04-22T21:14:23Z

Andreabont: Replaced content with "Here is a list of some of the Miosix APIs: API list"

Here is a list of some of the Miosix APIs: [[API list]]

API list

2014-04-22T21:13:51Z

Andreabont: Created page with "Here is a list of some of the Miosix APIs, currently far form being complete * The Serial port tutorial explains how to interface to a computer through the C functions ''..."

Here is a list of some of the Miosix APIs, currently far form being complete

* The [[Serial port tutorial]] explains how to interface to a computer through the C functions ''printf()/scanf()'' or the C++ ''cin/cout'' objects.
* The [[Filesystem tutorial]] explains how to read/write to files on a SD or MicroSD card using the standard C/C++ API.
* The [[Pthread tutorial]] shows the basics of multithreading in Miosix using the standard [https://en.wikipedia.org/wiki/Pthread Pthread] API.
* The [[Native thread tutorial]] shows how to use the Miosix-specific thread API.
* The [[GPIO tutorial]] shows how to interface with external hardware devices using the GPIO API.
* The [[HD44780 LCD tutorial]] shows how to connect a standard alphanumeric LCD to a board running Miosix.
* The [[Servo tutorial]] shows how to interface with servomotors from Miosix.

[[Category:API]]

Category:Boards

2014-04-22T21:11:55Z

Andreabont: Created page with "Boards."

Boards.

Category:Libraries

2014-04-22T21:07:13Z

Andreabont:

Category:Libraries

2014-04-22T21:06:50Z

Andreabont: Created page with "Libraries are additional components not part of the Miosix kernel that can be downloaded to add functionality to the kernel. *mxgui is a GUI library for graphic displays *mxu..."

Libraries are additional components not part of the Miosix kernel that can be downloaded to add functionality to the kernel.

*mxgui is a GUI library for graphic displays
*mxusb is an USB stack, currently targeting stm32f1 microcontrollers only.

GPIO tutorial

2014-04-22T21:05:42Z

Andreabont: /* Related pages */

Include statements and namespace required to use this library
<source lang="CPP">
#include <miosix.h>
using namespace miosix;
</source>
This is a C++ library, it cannot be used from a C source file.

A [https://en.wikipedia.org/wiki/GPIO GPIO] or general purpose input-output is a software-controllable pin of a microcontroller. To be able to control multiple GPIOs at the same time, most microcontrollers group GPIOs in ports, so GPIOs are specified by a port name, and a pin number within the port. The STM32 use letters to identify ports, so the GPIO 0 of port A is called PA0. The GPIO port and number are often specified at the pin headers on development boards such as the [[stm32f407vg_stm32f4discovery|STM32F4 Discovery]], in order to make it easy to connect wires to the correct GPIO. On the contrary, NXP uses numbers also for the ports, so the GPIO 0 of port 1 is called P1.0.

== Declaring GPIOs ==

A GPIO in Miosix is accessed using a C++ template class, the rationale behind this choice can be found [http://www.webalice.it/fede.tft/stm32/stm32_gpio_and_template_metaprogramming.html in this article], but in short it provides both optimal performance and a high-level API.

As an example, assume there is a blue LED connected to GPIO PD15 and a button connected to PA0, to control them in software you first have to declare the GPIOs using the following syntax

<source lang="CPP">
typedef Gpio<GPIOD_BASE,15> blueLed;
typedef Gpio<GPIOA_BASE,0> button;
</source>

A declaration like this can appear both inside a function, if you are going to use the GPIO only inside that function, or be put at the top of a source file, to access the GPIO from all the functions of that file. Notice how GPIO'''D'''_BASE means that this is a GPIO of port '''D''', and 15 is the GPIO number within the port. This declaration introduces a template named blueLed that can later be used to access the GPIO.

A common mistake is to declare the GPIO like this

<source lang="CPP">
/* DON'T WRITE CODE LIKE THIS */
typedef Gpio<GPIOD_BASE,15> pd15;
typedef Gpio<GPIOA_BASE,0> pa0;
</source>

While the following code will work, it is discouraged to choose the GPIO id as the name of the template. It is way better to try using a name related to the function that the GPIO will be used for, as it leads to code that is easier to read and understand. For example, the first GPIO is connected to a blue LED, so blueLed is an appropriate name.

== Configuring GPIOs ==

Once you have declared a GPIO, you need to to configure it before using it. The most basic level of configuration is to select the GPIO ''direction'', i.e, whether it is going to be used as an output, or an input.

If a GPIO is configured as an output software can control the voltage at that pin, by selecting between a logic level 0, which corresponds to 0V, or a logic 1, whose voltage is VDD, which is the voltage used to power the microcontroller, in most cases 3.3V for the typical microcontrollers supported by Miosix.

If a GPIO is configured as an input, software can sense the logic level at the pin, reading a logic level 0 if the voltage is close to 0V, or a logic 1 if it is close to VDD. Note that if the voltage is closed to hald of VDD, or if the GPIO is not connected to anything, the reading could be either 0 or 1, see the discussion about [https://en.wikipedia.org/wiki/Pull-up_resistor pull-up resistors] on Wikipedia for that.

To configure the GPIO you can use the ''mode()'' member function of the GPIO class. For example, in your ''main()'' function you can do

<source lang="CPP">
int main()
{
blueLed::mode(Mode::OUTPUT);
button::mode(Mode::INPUT);
}
</source>

Note that all boards supported by Miosix have the ''OUTPUT'' and ''INPUT'' modes, but may have more options.

Some for example, may have software controllable on-chip pull-up and/or pull-down resistors, or an analog input mode connected to an ADC to read analog voltages. The list of supported modes can be found in the gpio_impl.h file of your microcontroller. For example, for the microcontroller in the [[stm32f407vg_stm32f4discovery|STM32F4 Discovery]] board, the file is in ''miosix/arch/cortexM4_stm32f4/common/interfaces-impl/gpio_impl.h''.

A noteworty example is the ALTERNATE function mode, that when selected connects the GPIO to some device-dependent hardware peripheral, such as an SPI, I2C or UART peripheral. In such a case, the pin stops being a GPIO in the sense that it is no longer software controllable, but is instead driven by the hardware peripheral. This is often used to implement communication protocols like SPI or I2C.

However, these device-specific extensions are not discussed further here.

== GPIO Writing ==

To write to an OUTPUT configured GPIO, you can used the ''high()'' and ''low()'' member functions, as shown in this example that blinks a LED

<source lang="CPP">
#include <miosix.h>
using namespace miosix;

typedef Gpio<GPIOD_BASE,15> blueLed;

int main()
{
blueLed::mode(Mode::OUTPUT);
for(;;)
{
blueLed::high(); //Turn the LED on
Thread::sleep(500); //Wait 500ms
blueLed::low(); //Turn the LED off
Thread::sleep(500); //Wait 500ms
}
}
</source>

== GPIO Reading ==

Reading from an INPUT configured GPIO is performed by using the ''value()'' member function, as shown in this example that polls a button every 10ms and turns on a LED for 10 seconds once it detects it is pressed.

<source lang="CPP">
#include <miosix.h>
using namespace miosix;

typedef Gpio<GPIOD_BASE,15> blueLed;
typedef Gpio<GPIOA_BASE,0> button;

int main()
{
blueLed::mode(Mode::OUTPUT);
button::mode(Mode::INPUT);
for(;;)
{
//Poll the button every 10ms until it is pressed
while(button::value()==0) Thread::sleep(10);

blueLed::high(); //Turn the LED on
Thread::sleep(10000); //Wait 10s
blueLed::low(); //Turn the LED off
}
}
</source>

A common mistake is to forget the sleep when polling for the button, resulting in a code like this

<source lang="CPP">
/* DON'T WRITE CODE LIKE THIS */
for(;;)
{
//Poll the button until it is pressed
while(button::value()==0) ;

blueLed::high(); //Turn the LED on
Thread::sleep(10000); //Wait 10s
blueLed::low(); //Turn the LED off
}
</source>

Although this code will work, it is bad. To see why, consider that Miosix is a multithreaded OS, so in the general case there will be other threads running other than your code, so it is not polite to spin in a while loop that may take an undefined time to complete chewing up 100% of the CPU. This will for sure prevent the kernel from putting the CPU in sleep resulting in a higher power consumption, and may slow down other threads that can have more important tasks to do than spinning on a GPIO.

But you may be thinking that your application needs to be notified of the button being pressed ''as soon as possible'' and even a few milliseconds of delay are too much. In this case, this code is '''even more wrong''', because Miosix is a timesharing system, so your code can and will be preempted by the operating system to prevent other threads from starving. If the event that you need to be notified about happens while your code is preempted, there will be a delay of up to a few milliseconds between the actual event and when you notice it anyway.

To deal with situations where you need to be notified of pin change events events as soon as possible you need something more complicated, such as an [[Interrupt on pin change]] that will call an interrupt routine in response to an event, usually offering a time determinism of a few tens of microseconds, or a [[Timer input capture]] channel that provides a timestamp of an event with an accuracy of a few tens of nanoseconds.

== Thread safety considerations ==

All microcontroller, for self-evident reasons, provide hardware support to allow writing to GPIOs configured as OUTPUT in a thread-safe way, so you are free to call the ''high()'' and ''low()'' (and ''value()'' as well) from multiple threads.

Unfortunately, configuring GPIOs is on most microcontrollers not thread-safe. That is, if you call ''mode()'' concurrently from multiple threads on the same GPIO port, you may inadvertently misconfigure some of the pins in that port.

There are two ways to work around that, configuring all GPIOs in the ''main()'' before spawning any thread, and disabling interrupts while configuring GPIOs.

=== Configuring GPIOs in the main() ===

If you configure all the GPIOs in the ''main()'', before spawning any thread, and later you no longer call ''mode()'' there are no way two threads could call ''mode()'' concurrently, and so there is no problem. However, this often goes against code modularity, and in some circumstances you may need to change a GPIO configuration at runtime.

=== Disabling interrupts while configuring GPIOs ===

To allow ''mode()'' to be freely called, you have to make sure no two concurrent calls to ''mode()'' can happen. Considering that configuring a GPIO is a very fast operation, it requires just a few clock cycles, this can be achieved by disabling interrupts while configuring the GPIOs. Keep in mind that disabling interrupts must be done with care, and striving as much as possible to minimize the amount of time spent with interrupts disables, so as not to interfere with the real-time capabilities of the Miosix kernel.

<source lang="CPP">
void someFunction()
{
[...] //Some code

{
FastInterruptDisableLock dLock;
blueLed::mode(Mode::OUTPUT);
button::mode(Mode::INPUT);
}

[...] //Some other code
}
</source>

Note the two curly braces surrounding the dLock object, that create a [https://en.wikipedia.org/wiki/Scope_%28computer_science%29 scope] delimiting the lines of code where interrupts are disabled.

As a last note, you could also use a global [https://en.wikipedia.org/wiki/Mutex mutex] instead of disabling interrupts, but as previously mentioned configuring a GPIO is a very fast operation, it requires just a few clock cycles, so using a mutex would introduce a significant overhead.

== Accessing GPIOs from multiple source files ==

When dealing with large projects, it is common to split them in multiple source files. To access the GPIO definitions from multiple source files it is common practice in Miosix to declare them in a C++ header file, and ''#include'' it where needed. If that file contains all the GPIOs of a specific board, is is often called ''hwmapping.h''. In such a case, [https://en.wikipedia.org/wiki/Namespace#Examples namespaces] can be used to group GPIOs by function. For an example, see the ''hwmapping.h'' file for the Sony smartwatch board [https://gitorious.org/miosix-kernel/miosix-kernel/source/0fb80132cd27fbd48021cd5a9adb21c90a9cb94e:miosix/arch/cortexM3_stm32f2/stm32f205rg_sony-newman/interfaces-impl/hwmapping.h].

== Related pages ==
* [[Example: Blinking led|Blinking led]]

[[Category:API]]

GPIO tutorial

2014-04-22T21:05:10Z

Andreabont:

Category:API

2014-04-22T20:47:54Z

Servo tutorial

2014-04-22T20:47:02Z

Andreabont:

Include statements and namespace required to use this library
<source lang="CPP">
#include "drivers/servo_stm32.h"
using namespace miosix;
</source>
This is a C++ library, it cannot be used from a C source file.

A servomotor is a device that allows to control the angular position of a shaft, like [https://www.sparkfun.com/products/10333 this one]. Servos work by reading a PWM signal with a fixed frequency, 50Hz by default, and a pulse period proportional to the desired angle.

== Supported boards ==

Miosix has a servo library that supports some boards using STM32 microcontrollers, namely the [[stm32f100rb_stm32vldiscovery]] and [[stm32f407vg_stm32f4discovery]].

== GPIO connection ==

The library supports up to 4 servo outputs, that must be connected to the following GPIOs (that the library configures as TIMER alternate function when the output is enabled).

* PB6 is the output 0
* PB7 is the output 1
* PB8 is the output 2
* PB9 is the output 3

== Library use ==

The library is a C++ class named ''SynchronizedServo''. It is a [https://en.wikipedia.org/wiki/Singleton_pattern singleton], so to instantiate it you have to call the ''instance()'' member function.

You can find examples on how to use the library in the [https://gitorious.org/miosix-kernel/miosix-kernel/source/0fb80132cd27fbd48021cd5a9adb21c90a9cb94e:miosix/_examples/servo miosix/_examples/servo] directory of the kernel.

=== Closed loop control support ===

If there is the need to run a closed loop control code using the servo as an actuator, the library supports a way to synchronize the controller with the servo waveform generation, using the ''waitForCycleBegin()'' member function in a loop. The value set with ''setPosition()'' will be output at the '''next''' cycle, so take into account the existence of a z^-1 in your plant model.

<source lang="CPP">
#include <stdio.h>
#include "drivers/servo_stm32.h"
using namespace miosix;

int main()
{
SynchronizedServo& servo=SynchronizedServo::instance();
servo.enable(0); //Enable channel 0 (connect servo to PB6)
servo.start();
for(;;)
{
//This loop will be executed 50 times a second, and be synchronized with the waveform generation
servo.waitForCycleBegin();
float pos=computeServoPosition();
servo.setPosition(0,pos);
}
}
</source>

== Thread safety considerations ==

The ''waitForCycleBegin()'' member function can be called by only one thread at a given time, so if you want to control more than one servo, be sure to put all the control code into only one loop. The other member functions are thread safe.

[[Category:API]]

GPIO tutorial

2014-04-22T20:46:54Z

Andreabont:

Windows Netbeans configuration

2014-04-22T10:37:25Z

Andreabont:

=== Installing the IDE ===

Download the [https://netbeans.org/downloads Netbeans IDE]. Among the possible versions choose the C/C++ version.
Netbeans is an IDE written in Java, so it requires the JDK to function. If you don't have the JDK installed, download it from [http://www.oracle.com/technetwork/java/index.html here] and install it before installing Netbeans.

=== Configuring the IDE ===

Netbeans is a generic C/C++ IDE, and once installed is not set up by default to develop for ARM microcontrollers and Miosix. So you need to configure it. This is a one-time step that you will have to do again only if you re-install the IDE.

Note: this assumes you have already installed the Miosix toolchain, if not read the [[Windows Quick Start]] tutorial first.

Open the Netbeans IDE (there should be an icon on the Desktop after installation) and click on "Tools > Options". From the top of the options window select the C/C++ panel, and click the "Add" button to add a compiler to Netbeans. As "Base directory" choose "C:\arm-miosix-eabi\arm-miosix-eabi\bin". Choose "GNU MinGW" as "Tool collection family", and "ARM_MIOSIX_EABI" as "Tool collection name".
Note that you '''must''' use the "ARM_MIOSIX_EABI" name, or you'll have problems later.
The C and C++ compiler should be automatically filled in by Netbeans, if not copy them from the screenshot below. Please note that make.exe should have '''no path''' otherwise compiling will fail.

[[File:Nbsetup1-windows.png]]

Last, you will need to set up the paths with the compiler libraries for code completion to work. Click on the "Code assistance" tab, and "C compiler" sub-tab. The list of folders and macro definitions should look like in this screenshot, if not, add the paths manually.

[[File:Nbsetup2-windows.png]]

Then click th "C++ compiler" sub-tab and check if the paths and macro definitions are correct. If not add the missing paths manually as in the next screenshot.

[[File:Nbsetup3-windows.png]]

Configuration is now complete. You can close the Options windows by clicking "Ok".

=== Building the Miosix kernel with Netbeans ===

Select "File > Open project" and select the "miosix_np_2" directory withn the Miosix top level directory.

[[File:Nbsetup4-windows.png]]

You may want to rename the project from the default "miosix_np_2" to the name of the project you are going to develop, by right clicking on the project name and selecting "Rename".

Miosix supports different boards, each of which has different board support packages and peripheral drivers. To get code completion support for your board you need to select it within the IDE, as in the following image

[[File:Nbsetup5-windows.png]]

Please note that in the [[Windows Quick Start]] you had to select the board to compile for by editing the [[Makefile.inc|miosix/config/Makefile.inc]]. The board selection within the IDE '''does not replace''' the need to edit Makefile.inc, they serve two different purposes:
* Board selection within the IDE is used by the IDE to set up code completion for your board
* Board selection in Makefile.inc tells the kernel for which board it needs to be compiled.
However, please note that you can edit Makefile.inc and [[miosix_settingls.h|miosix/config/miosix_settings.h]] as regular source files within the IDE, without the need to use Notepad++.

You can open main.cpp (double click on it from the left pane), ant start typing your code. Code completion is invoked by typing the first letters of the function, variable, class or member function and hitting "Ctrl-space". Netbeans also integrates with Doxygen documentation, so you can see the documentation for Miosix classes and functions directly from the IDE.

[[File:Nbsetup6-windows.png]]

Building is performed by clicking the hammer icon above the source code editor. The Output window will appear below the source editor showing the compilation progress and eventual compiler errors.
There is no known way to transfer the compiled program on a microcontroller board directly from the IDE, for this you will have to use the QSTLink2 tools as explained in [[Windows Quick Start]].

[[Category:Installation and Configuration]]

Example: Thread

2014-04-13T21:12:20Z

Andreabont:

=== Native ===
<source lang="cpp">
#include <stdio.h>
#include <string.h>
#include "miosix.h"

using namespace miosix;

Mutex mutex;
ConditionVariable cond,ack;
char c=0;

void threadfunc(void *argv)
{
Lock<Mutex> lock(mutex);
for(int i=0;i<(int)argv;i++)
{
ack.signal();
while(c==0) cond.wait(lock);
printf("%c",c);
c=0;
}
}

int main()
{
const char str[]="Hello world\n";
Thread *thread;
thread=Thread::create(threadfunc,2048,1,(void*)strlen(str),Thread::JOINABLE);
{
Lock<Mutex> lock(mutex);
for(int i=0;i<strlen(str);i++)
{
c=str[i];
cond.signal();
if(i<strlen(str)-1) ack.wait(lock);
}
}
thread->join();
}
</source>

=== Pthread ===
<source lang="cpp">
#include <stdio.h>
#include <string.h>
#include <pthread.h>

pthread_mutex_t mutex=PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond=PTHREAD_COND_INITIALIZER;
pthread_cond_t ack=PTHREAD_COND_INITIALIZER;
char c=0;

void *threadfunc(void *argv)
{
pthread_mutex_lock(&mutex);
for(int i=0;i<(int)argv;i++)
{
pthread_cond_signal(&ack);
while(c==0) pthread_cond_wait(&cond,&mutex);
printf("%c",c);
c=0;
}
pthread_mutex_unlock(&mutex);
}

int main()
{
getchar();
const char str[]="Hello world\n";
pthread_t thread;
pthread_create(&thread,NULL,threadfunc,(void*)strlen(str));
pthread_mutex_lock(&mutex);
for(int i=0;i<strlen(str);i++)
{
c=str[i];
pthread_cond_signal(&cond);
if(i<strlen(str)-1) pthread_cond_wait(&ack,&mutex);
}
pthread_mutex_unlock(&mutex);
pthread_join(thread,NULL);
}
</source>

[[Category:Examples]]

Example: Thread

2014-04-13T21:10:35Z

Andreabont: Created page with "=== Native === <source lang="cpp"> // // To build this example modify the Makefile so that // SRC := native_thread_example.cpp // #include <stdio.h> #include <string.h> #incl..."

=== Native ===
<source lang="cpp">
//
// To build this example modify the Makefile so that
// SRC := native_thread_example.cpp
//

#include <stdio.h>
#include <string.h>
#include "miosix.h"

using namespace miosix;

Mutex mutex;
ConditionVariable cond,ack;
char c=0;

void threadfunc(void *argv)
{
Lock<Mutex> lock(mutex);
for(int i=0;i<(int)argv;i++)
{
ack.signal();
while(c==0) cond.wait(lock);
printf("%c",c);
c=0;
}
}

int main()
{
const char str[]="Hello world\n";
Thread *thread;
thread=Thread::create(threadfunc,2048,1,(void*)strlen(str),Thread::JOINABLE);
{
Lock<Mutex> lock(mutex);
for(int i=0;i<strlen(str);i++)
{
c=str[i];
cond.signal();
if(i<strlen(str)-1) ack.wait(lock);
}
}
thread->join();
}
</source>

=== Pthread ===
<source lang="cpp">
//
// To build this example modify the Makefile so that
// SRC := pthread_example.cpp
//

#include <stdio.h>
#include <string.h>
#include <pthread.h>

pthread_mutex_t mutex=PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond=PTHREAD_COND_INITIALIZER;
pthread_cond_t ack=PTHREAD_COND_INITIALIZER;
char c=0;

void *threadfunc(void *argv)
{
pthread_mutex_lock(&mutex);
for(int i=0;i<(int)argv;i++)
{
pthread_cond_signal(&ack);
while(c==0) pthread_cond_wait(&cond,&mutex);
printf("%c",c);
c=0;
}
pthread_mutex_unlock(&mutex);
}

int main()
{
getchar();
const char str[]="Hello world\n";
pthread_t thread;
pthread_create(&thread,NULL,threadfunc,(void*)strlen(str));
pthread_mutex_lock(&mutex);
for(int i=0;i<strlen(str);i++)
{
c=str[i];
pthread_cond_signal(&cond);
if(i<strlen(str)-1) pthread_cond_wait(&ack,&mutex);
}
pthread_mutex_unlock(&mutex);
pthread_join(thread,NULL);
}
</source>

[[Category:Examples]]

User talk:Fede.tft

2014-04-13T21:07:32Z

Andreabont: /* Remove redirect */ new section

== Remove redirect ==

This redirect is useful: 
https://miosix.org/wiki/index.php?title=Blinking_led&redirect=no 
I moved the page, but I can't suppress or remove the redirect. 
--[[User:Andreabont|Andreabont]] ([[User talk:Andreabont|talk]]) 23:07, 13 April 2014 (CEST)

Example: Blinking led

2014-04-13T21:03:50Z

Andreabont: Andreabont moved page Blinking led to Example: Blinking led

=== Simple blink ===
<source lang="cpp">
#include <cstdio>
#include <unistd.h>
#include "miosix.h"

using namespace std;
using namespace miosix;

typedef Gpio<GPIOC_BASE,7> led;

int main()
{

led::mode(Mode::OUTPUT);

for(;;) {
led::high();
sleep(1);
led::low();
sleep(1);
}

return 0;

}
</source>

[[Category:Examples]]

Example: Blinking led

2014-04-13T21:01:42Z

Andreabont:

Windows Quick Start

2014-04-13T20:54:40Z

Andreabont: Fix

=== 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.

* 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
* 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.

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 [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...)

=== 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.

[[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.

<source lang="bash">
git clone https://git.gitorious.org/miosix-kernel/miosix-kernel.git
cd miosix-kernel
git fetch origin
git checkout -b testing origin/testing
exit
</source>

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.

[[File: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 [[Makefile.inc|miosix/config/Makefile.inc]] and [[miosix_settingls.h|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:

<source lang="bash">
##
## 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
</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, 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
<source lang="CPP">
//#define JTAG_DISABLE_SLEEP
</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 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.

'''Blink a LED'''

Open the ''main.cpp'' file in the top-level directory using Notepad++, and replace its content with the following program:
<source lang="CPP">
#include <miosix.h>
using namespace miosix;
int main()
{
for(;;)
{
ledOn();
Thread::sleep(1000);
ledOff();
Thread::sleep(1000);
}
}
</source>
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.

[[File:Openterminalwindows.png]]

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

[[File: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 [[Miosix code size optimization|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

[[File: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.

[[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, 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.

=== What's next? ===

You have finished the installation of the Miosix Toolchain. You may want to [[Quick start#IDE Configuration|install and configure an IDE]], or the [[Quick start#In-circuit debugger|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.

[[Category:Installation and Configuration]]

Quick start

2014-04-13T13:11:48Z

Andreabont: Add category

To start using Miosix you need a patched version of the GCC compiler to support the Miosix thread model and git to download the kernel sources. Optionally you can also use an IDE to simplify code development, and an in-circuit debugger to speed up bug fixing.

''' Changes with respect to Miosix 1.x '''

A word of warning if you are a long-time user of Miosix: please note that in Miosix 2.0 there were significant changes.
First of all, Miosix 2.0 uses GCC 4.7.3 and is no longer compatible with the old GCC 4.5.2 used in Miosix 1.x, so you need to upgrade your compiler.
Second, the preferred way to install the compiler is through a precompiled installer available for both Linux and Windows. If you want, though, you can still build the compiler from sources.
Last, keep in mind that the compiler patches are still a work in progress. When doing a 'git pull' you may need to upgrade the compiler too.

=== Getting started ===

This section will guide you through the installation of the minimum requirements to start using Miosix: installing the compiler, and downloading the kernel.

* [[Linux Quick Start|Getting Started on Linux]]
* [[Windows Quick Start|Getting Started on Windows]]

=== IDE Configuration ===

The default IDE to develop for Miosix is [https://netbeans.org/ Netbeans]. However, it does not come with Miosix support out of the box, so you have to configure it first.

* [[Linux Netbeans configuration]]
* [[Windows Netbeans configuration]]

Another alternative is Eclipse, which has the added feature to allow in-circuit debugging directly from the IDE.

TODO: How to set up Eclipse

=== In-circuit debugger ===

An in-circuit debugger allows to physically halt the CPU inside a microcontroller, single-step it and view all the variables at any given time. It is a powerful tool to debug software running on a microcontroller. Miosix uses GDB and [http://openocd.sourceforge.net openocd] for in-circuit debugging.

* [[Linux Debugger configuration]]
* [[Windows Debugger configuration]]

[[Category:Installation and Configuration]]

Category:Installation and Configuration

2014-04-13T13:11:17Z

Andreabont: Created page with "Installation and Configuration:"

Installation and Configuration:

Windows Quick Start

2014-04-13T13:10:56Z

Andreabont: Add category

=== 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.

* 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
* 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.

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 [[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...)

=== 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.

[[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.

<source lang="bash">
git clone https://git.gitorious.org/miosix-kernel/miosix-kernel.git
cd miosix-kernel
git fetch origin
git checkout -b testing origin/testing
exit
</source>

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.

[[File: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 [[Makefile.inc|miosix/config/Makefile.inc]] and [[miosix_settingls.h|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:

<source lang="bash">
##
## 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
</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''.

Next, edit the ''miosix_settings.h'' using Notepad++ and uncomment (by removing the '//' at the start of the line) the following line
<source lang="CPP">
//#define JTAG_DISABLE_SLEEP
</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.

'''Blink a LED'''

Open the ''main.cpp'' file in the top-level directory using Notepad++, and replace its content with the following program:
<source lang="CPP">
#include <miosix.h>
using namespace miosix;
int main()
{
for(;;)
{
ledOn();
Thread::sleep(1000);
ledOff();
Thread::sleep(1000);
}
}
</source>
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.

[[File:Openterminalwindows.png]]

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

[[File: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 [[Miosix code size optimization|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

[[File: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.

[[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.

=== What's next? ===

You have finished the installation of the Miosix Toolchain. You may want to [[Quick start#IDE Configuration|install and configure an IDE]], or the [[Quick start#In-circuit debugger|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.

[[Category:Installation and Configuration]]

Linux Quick Start

2014-04-13T13:09:47Z

Andreabont: Add category

This page explains how to install the precompiled Miosix Toolchain. If you prefer compiling GCC from sources, see [[Building GCC from sources]].

=== Before you begin ===

'''64 bit Linux distros'''

The precompiled Miosix Toolchain is compiled for 32bit x86, to be compatible with as many Linux installations as possible. If you have a 64bit OS, you need to install a few 32bit libraries to be able to use it.

<source lang="bash">
sudo apt-get install libstdc++6:i386 # Install 32bit compatibility libraries for Ubuntu/Debian
sudo pacman -S lib32-libstdc++5 # Install 32bit compatibility libraries for Arch Linux
</source>

''' QSTLink2 '''

If you want to program STM32 microcontrollers, you will also need a tool to the transfer your programs to the microcontroller. A popular choice for boards like the ''stm32f4discovery'' that have an embedded STLinkV2 USB programmer/debugger is [https://code.google.com/p/qstlink2 QSTLink2]. The installation on Ubuntu/Debian requires to add a ''ppa'' and install it via ''apt-get''. Also, it is recomended to install the udev rules, which allow QSTLink2 to connect to the USB port without the need to run it from root.

<source lang="bash">
sudo add-apt-repository ppa:mobyfab/qstlink2
sudo apt-get update
sudo apt-get install qstlink2
wget https://raw.githubusercontent.com/mobyfab/QStlink2/master/res/49-stlinkv2.rules
sudo mv 49-stlinkv2.rules /etc/udev/rules.d
sudo chown root:root /etc/udev/rules.d/49-stlinkv2.rules
</source>

An alternative tool to program STM32 microcontrollers using the serial port bootloader is [https://code.google.com/p/stm32flash stm32flash]. Finally, for historical reasons, the Miosix Toolchain includes ''lpc21isp'', a tool to program LPC2000 microcontrollers using their serial bootloader.

''' Serial port setup '''

Miosix redirects ''stdin''/''stdout'' to a serial port by default on most boards, so it is important to set up serial ports correctly on your development machine. On most Linux distros serial ports, both the physical ones like ''/dev/ttyS0'' and the USB to serial adapters like ''/dev/ttyUSB0'' are owned by the ''dialout'' group, so you need to add your user to that group before you can access them.

<source lang="bash">
sudo usermod -a -G dialout `id -un` # Add yourself to the dialout group
</source>

Note that you may need to reboot your computer before the change takes effect. Also, you need a program to interact with the serial port, like ''GNU screen''.

<source lang="bash">
sudo apt-get install screen # For Ubuntu/Debian
sudo pacman -S screen # For Arch Linux
</source>

=== Install the Miosix Toolchain ===

Download the latest version of the [http://miosix.org/toolchain/MiosixToolchainInstaller.run Miosix Toolchain] and launch it. The installer will ask for your root password to copy the compiler to the ''/opt/arm-miosix-eabi'' directory, and put symlinks to ''/usr/bin''.

<source lang="bash">
wget http://miosix.org/toolchain/MiosixToolchainInstaller.run
sh MiosixToolchainInstaller.run
</source>

If you do not trust the installer and want to verify its content, or you want to install it locally, it is possible to extract the content of the installer with the following command.

<source lang="bash">
sh MiosixToolchainInstaller.run --noexec --target arm-miosix-eabi
</source>

Keep in mind that for a local install you will need to set the ''PATH'' environment variable to the ''arm-miosix-eabi/bin'' directory.

=== Get the Miosix kernel sources ===

The preferred way to download the Miosix kernel is through [https://en.wikipedia.org/wiki/Git_%28software%29 git]. If you do not already have it installed you can install it now

<source lang="bash">
sudo apt-get install git # For Ubuntu/Debian
sudo pacman -S git # For Arch Linux
</source>

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.

<source lang="bash">
git clone https://git.gitorious.org/miosix-kernel/miosix-kernel.git
cd miosix-kernel
git fetch origin
git checkout -b testing origin/testing
</source>

=== 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.

[[File:Miosixtopleveldirectorylinux.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 [[Makefile.inc|miosix/config/Makefile.inc]] and [[miosix_settings.h|miosix/config/miosix_settings.h]]. Open the first one, and select your board. To do so, look for the ''OPT_BOARD'' section of the file, which looks like this:

<source lang="bash">
##
## 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
</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''.

Next, edit the ''miosix_settings.h'' file and uncomment (by removing the '//' at the start of the line) the following line
<source lang="CPP">
//#define JTAG_DISABLE_SLEEP
</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.

'''Blink a LED'''

Open the ''main.cpp'' file in the top-level directory, and replace its content with the following program:
<source lang="CPP">
#include <miosix.h>
using namespace miosix;
int main()
{
for(;;)
{
ledOn();
Thread::sleep(1000);
ledOff();
Thread::sleep(1000);
}
}
</source>
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 terminal in the Miosix top-level directory and type ''make''. If all goes well, the result should look like this.

[[File:Makeoutputlinux.png]]

Otherwise, compiler errors will appear in the shell. 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 [[Miosix code size optimization|reduce code size]].

'''Programming'''

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

[[File:Findqstlink2guilinux.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.

[[File:Qstlink2flashinglinux.png]]

Note that, regardless of using QSTLink2 form the shell 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.

=== What's next? ===

You have finished the installation of the Miosix Toolchain. You may want to [[Quick start#IDE Configuration|install and configure an IDE]], or the [[Quick start#In-circuit debugger|debugger]].

=== Uninstall the compiler ===

If for some reason you need to uninstall the compiler, there is an uninstall script in the ''/opt/arm-miosix-eabi'' directory (Note: if you have built the compiler from sources the uninstall script may not be there). Running the script will uninstall the compiler and the symbolic links in the ''/usr/bin'' directory. Just like the install script, the uninstaller will ask for your root password to be able to remove the installed files.

There is no need to uninstall and old compiler to install a new one, the installer will take care of that automatically. However, if you have installed the compiler and now you want to build it from sources, you first need to uninstall the old compiler.

<source lang="bash">
cd /opt/arm-miosix-eabi
./uninstall.sh
</source>

If you have chosen to install the compiler locally (i.e: not in the '/opt/arm-miosix-eabi' directory), simply remove the compiler directory.

[[Category:Installation and Configuration]]

Linux Quick Start

2014-04-13T13:08:12Z

Andreabont:

Quick start

2014-04-13T13:04:15Z

Andreabont:

Category:Examples

2014-04-12T20:32:02Z

Andreabont: Created page with "Examples:"

Examples:

Example: Blinking led

2014-04-12T20:28:08Z

Andreabont: Created page with "== Simple Example == <source lang="cpp"> #include <cstdio> #include <unistd.h> #include "miosix.h" using namespace std; using namespace miosix; typedef Gpio<GPIOC_BASE,7> l..."

== Simple Example ==
<source lang="cpp">
#include <cstdio>
#include <unistd.h>
#include "miosix.h"

using namespace std;
using namespace miosix;

typedef Gpio<GPIOC_BASE,7> led;

int main()
{

led::mode(Mode::OUTPUT);

for(;;) {
led::high();
sleep(1);
led::low();
sleep(1);
}

return 0;

}
</source>

[[Category:Examples]]