Add pin details to porting guide

Author: gpsimenos

docs/porting/standard_pin_names/pin_names_porting.md

@@ -16,17 +16,69 @@ The generic guidelines currently define rules for the naming of LED pins, button
 * A pin cannot be assigned to itself
 * A pin cannot be defined as `NC` (not connected)
 
-Please refer to the design document for the full specification.
+### Definition of LEDs
+
+Only add LEDs that are available on the board. This is an example on how to define LEDs in PinNames.h:
+
+    // Px_xx relates to the processor pin connected to the LED
+    #define LED1 Px_xx  // LED1
+    #define LED2 Px_xx  // LED2
+    #define LED3 Px_xx  // LED3
+    #define LED4 Px_xx  // LED4
+    .  
+    .  
+    #define LEDN Px_xx  // LEDN
+
+### Definition of buttons
+
+Only add buttons that are available on the board. This is an example on how to define buttons in PinNames.h:
+
+    // Px_xx relates to the processor pin connected to the button  
+    #define BUTTON1 Px_xx  // BUTTON1
+    #define BUTTON2 Px_xx  // BUTTON2
+    #define BUTTON3 Px_xx  // BUTTON3
+    #define BUTTON4 Px_xx  // BUTTON4
+    .  
+    .  
+    #define BUTTONN Px_xx  // BUTTONN
+### Definition of UART pins
+
+This is an example on how to define UART names in PinNames.h:
+
+    typedef enum {
+    ...
+    // Px_xx relates to the processor pin connected to the UART
+    USBTX       = Px_xx,
+    USBRX       = Px_xx,
+    ...
+    } PinName;
+
+### Non-valid definitions
+
+If either LEDs or buttons are not available, they should not be defined.
+This allows for unavailable LEDs or BUTTONs to be caught in Mbed OS allowing the corresponding errors to be generated.
+   
+    #define LED1 PB_0  // LED1 is valid
+    #define LED2 LED1  // Not valid as it's duplicate and LED2 does not exist on the board
+    #define LED3 PB_0  // Not valid as it's duplicate and LED3 does not exist on the board
+    #define LED4 NC    // Not valid definition as LED4 does not exist
+
+    #define BUTTON1 PB_1    // BUTTON1 is valid
+    #define BUTTON2 BUTTON1 // Not valid as it's duplicate and BUTTON2 does not exist on the board
+    #define BUTTON3 PB_1    // Not valid as it's duplicate and BUTTON3 does not exist on the board
+    #define BUTTON4 NC      // Not valid as BUTTON4 does not exist
 
 ## Arduino Uno Pin Names
 The Arduino Uno guidelines currently define rules for the naming of the Arduino Uno connector pins, the functionality that each pin must support and the definition of Arduino Uno pin aliases. In summary, rules that apply to all Arduino pins are:
 * All ARDUINO_UNO_XXX pins are defined
 * A pin cannot be assigned to itself
 * A pin cannot be defined as `NC` (not connected)
 
-Also, every board that has the Arduino Uno connector must include `ARDUINO_UNO` in `targets.json` in the `supported_form_factors` list.
+In Arduino Uno compliant development boards, the `ARDUINO_UNO` name should be defined as a supported form factor in targets.json file:
 
-There are additional rules for different types of pins. Below is a summary of those rules.
+    "supported_form_factors": [
+            "ARDUINO_UNO"
+        ],
 
 ### Digital and Analog pins
 * Pins must be defined in a `PinName` enum
@@ -35,18 +87,78 @@ There are additional rules for different types of pins. Below is a summary of th
 * Analog pins must provide ADC functionality
 * A physical MCU pin can be assigned to no more than one Arduino Uno pin
 
+The Arduino Uno (Rev3) form factor for Mbed boards must support and define both D0-D15 pins for digital GPIO and A0-A5 pins for analog input as part of the default standard. These pins should be defined in PinNames.h file within a PinName enum. The prefix `ARDUINO_UNO_` distinguishes these pins from pins defined for other custom or common connectors that may have similar pin names. 
+
+The analog input signals in the Arduino Uno connector must be supported on at least the Ax pins.
+
+    #ifdef TARGET_FF_ARDUINO_UNO
+    // Arduino Uno (Rev3) pins
+    // Px_xx relates to the processor pin connected to the Arduino Uno (Rev3) connector pin
+    ARDUINO_UNO_D0 = Px_xx,
+    ARDUINO_UNO_D1 = Px_xx,
+    ARDUINO_UNO_D2 = Px_xx,
+    ARDUINO_UNO_D3 = Px_xx,
+    ARDUINO_UNO_D4 = Px_xx,
+    ARDUINO_UNO_D5 = Px_xx,
+    ARDUINO_UNO_D6 = Px_xx,
+    ARDUINO_UNO_D7 = Px_xx,
+    ARDUINO_UNO_D8 = Px_xx,
+    ARDUINO_UNO_D9 = Px_xx,
+    ARDUINO_UNO_D10 = Px_xx,
+    ARDUINO_UNO_D11 = Px_xx,
+    ARDUINO_UNO_D12 = Px_xx,
+    ARDUINO_UNO_D13 = Px_xx,
+    ARDUINO_UNO_D14 = Px_xx,
+    ARDUINO_UNO_D15 = Px_xx,
+
+    ARDUINO_UNO_A0 = Px_xx,
+    ARDUINO_UNO_A1 = Px_xx,
+    ARDUINO_UNO_A2 = Px_xx,
+    ARDUINO_UNO_A3 = Px_xx,
+    ARDUINO_UNO_A4 = Px_xx,
+    ARDUINO_UNO_A5 = Px_xx,
+    #endif // TARGET_FF_ARDUINO_UNO
+
+If the development board has the Arduino Uno connector in hardware, but does not comply with the Arduino Uno standard, whether it be with alternate functionality pins or non connected pins, the board should not be defined as Arduino Uno compliant and `ARDUINO_UNO` should not be added as a supported form factor in targets.json. Note this may result in a warning being generated at compile time to inform the user.
+
 ### I2C, SPI and UART pins
 * Pins D14, D15 must provide I2C functionality (SDA, SCL)
 * Pins D10, D11, D12, D13 must provide SPI functionality (CS, MOSI, MISO, SCK)
 * Pins D0, D1 must provide UART functionality (RX, TX) 
 
+All I2C, SPI and UART pin name alias definitions for the Arduino Uno (Rev3) connector pins is defined in the Mbed OS HAL (hal/include/hal/ArduinoUnoAliases.h) and are common to all Arduino Uno compliant targets:
+
+    #ifdef TARGET_FF_ARDUINO_UNO
+    // Arduino Uno I2C signals aliases
+    #define ARDUINO_UNO_I2C_SDA ARDUINO_UNO_D14
+    #define ARDUINO_UNO_I2C_SCL ARDUINO_UNO_D15
+
+    // Arduino Uno SPI signals aliases
+    #define ARDUINO_UNO_SPI_CS   ARDUINO_UNO_D10
+    #define ARDUINO_UNO_SPI_MOSI ARDUINO_UNO_D11
+    #define ARDUINO_UNO_SPI_MISO ARDUINO_UNO_D12
+    #define ARDUINO_UNO_SPI_SCK  ARDUINO_UNO_D13
+
+    // Arduino Uno UART signals aliases
+    #define ARDUINO_UNO_UART_TX ARDUINO_UNO_D1
+    #define ARDUINO_UNO_UART_RX ARDUINO_UNO_D0
+    #endif // TARGET_FF_ARDUINO_UNO
+
 ### Other pins
 * Mbed boards may provide PWM and timer functionality on certain Dx pins
 * Applications cannot assume consistent availability of PWM and timer pins across Mbed boards
 * The reset pin must be wired correctly in hardware but is not required to be defined in `PinNames.h`
 
-Please refer to the design document for the full specification.
+In the Arduino Uno standard there are only 6 PWM and timers available on pins D3, D5, D6, D9, D10 and D11.
+Mbed boards may support the usage of PWM and timers functions in some Dx pinnames. Although this is recomended as per the Arduino Uno standard, it's not a mandatory as requirement to be compliant with the Arduino Uno standard for Mbed boards.
+
+Note this might be one of the main differencess accross Mbed boards and therefore the application should not assume the same behaviour for PWM and Timers for them.
+
+The Reset signal in the Arduino Uno header is a bidirectional reset that will put both a connected Arduino Uno shield and the Mbed board into a reset state. There is a hardware requirement to wire this signal correctly; however there is no need to define the Reset signal in the BSP for the Mbed board.
 
+The Vin signal is defined in the Arduino Uno standard and should be implemented between 7V to 12V. In some cases this signal may be implemented as a bi-directional power supply.
+A warning should be included in the Mbed platform's website if it isn't implemented in the correct voltage range.
+Note if a Partner or developer designs an Arduino Uno shield and expects 7V-12V on the Vin, it will have power issues with a controller board supplying less then 7V and will likely cause the Arduino Uno shield to not power up correctly
 
 ## Target markers