GPIO tutorial - Revision history

Andreabont: /* Related pages */

2014-04-22T21:05:42Z

← Older revision		Revision as of 21:05, 22 April 2014
Line 168:		Line 168:

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

	[[Category:API]]		[[Category:API]]

Andreabont at 21:05, 22 April 2014

2014-04-22T21:05:10Z

← Older revision		Revision as of 21:05, 22 April 2014
Line 166:		Line 166:

	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].		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 ==
			* [[Blinking led]]

	[[Category:API]]		[[Category:API]]

Andreabont at 20:46, 22 April 2014

2014-04-22T20:46:54Z

← Older revision		Revision as of 20:46, 22 April 2014
Line 166:		Line 166:

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

			[[Category:API]]

Fede.tft at 15:08, 22 April 2014

2014-04-22T15:08:37Z

← Older revision		Revision as of 15:08, 22 April 2014
Line 162:		Line 162:

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

Fede.tft at 15:01, 22 April 2014

2014-04-22T15:01:51Z

@@ Line 95: / Line 95: @@
      blueLed::mode(Mode::OUTPUT);
      button::mode(Mode::INPUT);
-   for(;;)
+    for(;;)
+     {
          //Poll the button every 10ms until it is pressed
@@ Line 124: / Line 124: @@
 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 between the actual event and when you notice it anyway.
+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.

Fede.tft at 14:35, 22 April 2014

2014-04-22T14:35:08Z

@@ Line 83: / Line 83: @@
 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">
@@ Line 110: / Line 95: @@
      blueLed::mode(Mode::OUTPUT);
      button::mode(Mode::INPUT);
-    for(;;)
+   for(;;)
+     {
-         //Poll the button until it is pressed
+         //Poll the button every 10ms until it is pressed
-         while(button::value()==0) ;
+         while(button::value()==0) Thread::sleep(10);
          blueLed::high();      //Turn the LED on
@@ Line 119: / Line 104: @@
          blueLed::low();       //Turn the LED off
+     }
+}
 </source>

Fede.tft at 14:33, 22 April 2014

2014-04-22T14:33:26Z

@@ Line 24: / Line 24: @@
 <source lang="CPP">
 typedef Gpio<GPIOD_BASE,15> pd15;
 typedef Gpio<GPIOA_BASE,0> pa0;
@@ Line 41: / Line 42: @@
 <source lang="CPP">
 typedef Gpio<GPIOD_BASE,15> blueLed;
 typedef Gpio<GPIOA_BASE,0> button;
@@ Line 48: / Line 110: @@
      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. 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.
+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.

Fede.tft at 13:51, 22 April 2014

2014-04-22T13:51:46Z

← Older revision		Revision as of 13:51, 22 April 2014
Line 7:		Line 7:

	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.		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.		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">
			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">
			typedef Gpio<GPIOD_BASE,15> blueLed;
			typedef Gpio<GPIOA_BASE,0> button;

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

Fede.tft at 13:16, 22 April 2014

2014-04-22T13:16:19Z

← Older revision		Revision as of 13:16, 22 April 2014
Line 5:		Line 5:
	</source>		</source>
	This is a C++ library, it cannot be used from a C source file.		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.

			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.

Fede.tft: Created page with "Include statements and namespace required to use this library #include using namespace miosix; This is a C++ library, it cannot be use..."

2014-04-22T12:41:00Z

Created page with "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 use..."

New page

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.