Merge pull request #1417 from ARMmbed/std-pin-names-porting

Standard Pin Names Porting and Developer Guide

Author: Donatien Garnier

docs.json

@@ -265,6 +265,16 @@
                                 }
                             ]
                         },
+                        {
+                            "title": "Standard Pin Names Developer Guide",
+                            "sources": [{
+                                    "path": "docs/porting/standard_pin_names/pin_names_dev_guide.md"
+                                },
+                                {
+                                    "path": "docs/porting/standard_pin_names/pin_names_dev_guide_arduino.md"
+                                }
+                            ]
+                        },
                         {
                             "title": "Serial (UART) APIs",
                             "sources": [{
@@ -1305,6 +1315,9 @@
                         {
                             "path": "docs/porting/target/gpio.md"
                         },
+                        {
+                            "path": "docs/porting/standard_pin_names/pin_names_porting.md"
+                        },
                         {
                             "path": "docs/porting/target/rtc.md"
                         },

docs/images/Arduino_Uno_Mbed.png

@@ -0,0 +1,64 @@
+## Introduction
+
+### Overview and assumptions
+
+Platform code should be portable across different Mbed supported boards with the same hardware capabilities or interfaces.
+
+This document provides general developer guidelines on pin names that apply to all boards but it's not specific to any type of connector.
+
+**_NOTE:_** there might be separate documents for pin names that apply to specific connectors.
+
+## Standard Pin Names
+
+### LEDs
+
+Available onboard LEDs are defined as `LEDx` e.g. `LED1`, `LED2`, ...
+
+The detection of available LEDs at application level can be done as follows:
+
+    #ifdef LED1
+        DigitalOut myLED(LED1);
+        myLED = 1;
+    #endif 
+
+Alternatively, if the usage of an LED is required, then the application can detect its availability and generate an error accordingly:
+
+    #ifndef LED1
+        #error This application requires the availability of an LED
+    #endif
+
+It's possible to define new names of LEDs related to its properties, like color or functionality. They can be defined as aliases in the application as shown below:
+
+    #define RED_LED    LED1
+    #define STATUS_LED LED2 
+
+However, these names do not apply to all boards and hence should not be used in official example applications.
+
+### Buttons
+
+Buttons that are available on a board will be defined as `BUTTONx` e.g. `BUTTON1`, `BUTTON2`, ...
+
+The detection of available buttons at application level can be done as follow:
+
+    #ifdef BUTTON1
+        DigitalIn myBUTTON(BUTTON1);
+        int input = myBUTTON.read();
+    #endif 
+
+Alternatively, if the usage of a button is required, then the application can detect its availability and generate an error accordingly:
+
+    #ifndef BUTTON1
+        #error This application requires the availability of a button
+    #endif 
+
+It's possible to define new names of buttons related to its properties. It's recommended to add a comment with a description. They can be defined as aliases at application level as shown below:
+
+    #define PUSH_BUTTON BUTTON1 // Momentary push Button
+
+However, these names do not apply to all boards and hence should not be used in official example applications.
+
+### UART
+
+Every Mbed board includes a serial interface to the host PC, which allows the console to print useful information about the application.
+
+The pins for the main serial interface are defined as `CONSOLE_TX` and `CONSOLE_RX`.

docs/porting/standard_pin_names/pin_names_dev_guide.md

@@ -0,0 +1,65 @@
+## Arduino Uno 
+
+The Arduino Uno connector is a standardised connector in Mbed, which has a set amount of exposed functionality. To achieve meaningful portability of application code across various Mbed boards that are Arduino Uno compliant, the pin names used for the connector pins are common across these boards.
+
+The following diagram shows the Arduino Uno standard for Mbed boards:
+![Static pinmap model](../../images/Arduino_Uno_Mbed.png) 
+
+**Digital and Analog pins**
+
+The Arduino Uno connector for Mbed boards supports both digital and analog pins. Please note that the Arduino Uno only supports analog inputs and does not support analog output functionality. Digital pin functionality such as GPIO output or input on the Arduino Uno header can be accessed from any of the pins labelled as ARDUINO_UNO_D0 to ARDUINO_UNO_D15 and ARDUINO_UNO_A0 to ARDUINO_UNO_A5. The analog input functionality on the Arduino Uno connector can only be accessed on pins ARDUINO_UNO_A0 to ARDUINO_UNO_A5. The full digital and analog pin alias list for the Arduino Uno connector can be seen below.  
+
+    ARDUINO_UNO_D0 
+    ARDUINO_UNO_D1 
+    ARDUINO_UNO_D2 
+    ARDUINO_UNO_D3 
+    ARDUINO_UNO_D4 
+    ARDUINO_UNO_D5 
+    ARDUINO_UNO_D6 
+    ARDUINO_UNO_D7 
+    ARDUINO_UNO_D8 
+    ARDUINO_UNO_D9 
+    ARDUINO_UNO_D10 
+    ARDUINO_UNO_D11 
+    ARDUINO_UNO_D12 
+    ARDUINO_UNO_D13 
+    ARDUINO_UNO_D14 
+    ARDUINO_UNO_D15 
+    
+    ARDUINO_UNO_A0 
+    ARDUINO_UNO_A1 
+    ARDUINO_UNO_A2 
+    ARDUINO_UNO_A3 
+    ARDUINO_UNO_A4 
+    ARDUINO_UNO_A5 
+    
+**SPI pins**
+
+The Arduino Uno connector for Mbed boards supports SPI functionality on specific pins and can be accessed using the pin alias's below  
+
+    ARDUINO_UNO_SPI_CS    or ARDUINO_UNO_D10
+    ARDUINO_UNO_SPI_MOSI  or ARDUINO_UNO_D11
+    ARDUINO_UNO_SPI_MISO  or ARDUINO_UNO_D12
+    ARDUINO_UNO_SPI_SCK   or ARDUINO_UNO_D13
+
+if you need more SPI chip selects(CS) for your application, these can be controlled using additional digital out pins with the alias explained previously on this page 
+
+**I2C pins**    
+
+The Arduino Uno connector for Mbed boards supports I2C functionality on specific pins and can be accessed using the pin alias's below. 
+
+    ARDUINO_UNO_I2C_SDA or ARDUINO_UNO_D14
+    ARDUINO_UNO_I2C_SCL or ARDUINO_UNO_D15
+
+**UART pins**    
+
+The Arduino Uno connector for Mbed boards supports UART functionality on specific pins and can be accessed using the pin alias's below 
+
+    ARDUINO_UNO_UART_TX or ARDUINO_UNO_D1
+    ARDUINO_UNO_UART_RX or ARDUINO_UNO_D0
+
+For more details about UART, please check the Mbed API.
+
+**PWM/Timer pins**    
+
+In the Arduino Uno standard, there are only 6 PWM and timers available on pins ARDUINO_UNO_D3, ARDUINO_UNO_D5, ARDUINO_UNO_D6, ARDUINO_UNO_D9, ARDUINO_UNO_D10 and ARDUINO_UNO_D11. However, Mbed boards may support the usage of PWM and timers functions on other pins as well.