Document and clean up wifi and LoRa modules, add ability in Python to get non-public targets (ARMmbed#247)

* Add a way to get target attributes for non public targets

* Document all WiFi and LoRa modules

* Fix some errors

* Fix another CMake error

Author: Jamie Smith

connectivity/drivers/802.15.4_RF/CMakeLists.txt

@@ -2,8 +2,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # The 'mbed-802.15.4-rf' target is lazily created because there might not be any subdirectories needing it at all.
-macro(create_802_15_4_target)
-	if(NOT TARGET create_802_15_4_target)
+macro(create_mbed_802_15_4_target)
+	if(NOT TARGET mbed-802.15.4-rf)
 		add_library(mbed-802.15.4-rf STATIC EXCLUDE_FROM_ALL)
 
 		# Nanostack drivers always require Mbed RTOS
@@ -14,29 +14,29 @@ macro(create_802_15_4_target)
 		        mbed-802.15.4-rf
 		)
 	endif()
-endmacro()
+endmacro(create_mbed_802_15_4_target)
 
 
 if("Freescale" IN_LIST MBED_TARGET_LABELS)
-	create_802_15_4_target()
+	create_mbed_802_15_4_target()
     add_subdirectory(TARGET_Freescale)
 elseif("Silicon_Labs" IN_LIST MBED_TARGET_LABELS)
-	create_802_15_4_target()
+	create_mbed_802_15_4_target()
     add_subdirectory(TARGET_Silicon_Labs)
 endif()
 
 if("COMPONENT_MICROCHIP_AT86RF=1" IN_LIST MBED_TARGET_DEFINITIONS)
-	create_802_15_4_target()
+	create_mbed_802_15_4_target()
 	add_subdirectory(COMPONENT_MICROCHIP_AT86RF)
 endif()
 
 if("COMPONENT_NXP_MCR20A=1" IN_LIST MBED_TARGET_DEFINITIONS)
-	create_802_15_4_target()
+	create_mbed_802_15_4_target()
 	add_subdirectory(COMPONENT_NXP_MCR20A)
 endif()
 
 if("COMPONENT_STM_S2_LP=1" IN_LIST MBED_TARGET_DEFINITIONS)
-	create_802_15_4_target()
+	create_mbed_802_15_4_target()
 	add_subdirectory(COMPONENT_STM_S2_LP)
 endif()
 

connectivity/drivers/wifi/CMakeLists.txt

@@ -1,20 +1,38 @@
 # Copyright (c) 2020-2021 ARM Limited. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-add_library(mbed-wifi STATIC EXCLUDE_FROM_ALL)
+# The 'mbed-wifi' target is lazily created because there might not be any subdirectories needing it at all.
+macro(create_mbed_wifi_target)
+	if(NOT TARGET mbed-wifi)
+		add_library(mbed-wifi STATIC EXCLUDE_FROM_ALL)
 
-add_subdirectory(TARGET_WICED EXCLUDE_FROM_ALL)
+		target_link_libraries(mbed-wifi
+		    PUBLIC
+		        mbed-rtos-flags
+		        mbed-netsocket-api
+		)
+	endif()
+endmacro()
 
-add_subdirectory(TARGET_STM EXCLUDE_FROM_ALL)
+
+# The WICED subdirectory is for wifi drivers developed using Infineon WICED framework.
+# https://community.infineon.com/t5/Knowledge-Base-Articles/WICED-Wi-Fi-FAQ/ta-p/247356
+if("WICED" IN_LIST MBED_TARGET_LABELS)
+	create_mbed_wifi_target()
+    add_subdirectory(TARGET_WICED EXCLUDE_FROM_ALL)
+endif()
+
+if("STM" IN_LIST MBED_TARGET_LABELS)
+    add_subdirectory(TARGET_STM EXCLUDE_FROM_ALL)
+endif()
 
 if("WHD" IN_LIST MBED_TARGET_LABELS)
+	create_mbed_wifi_target()
     add_subdirectory(COMPONENT_WHD EXCLUDE_FROM_ALL)
 endif()
 
-add_subdirectory(esp8266-driver)
+if("COMPONENT_ESPRESSIF_ESP8266=1" IN_LIST MBED_TARGET_DEFINITIONS)
+	create_mbed_wifi_target()
+    add_subdirectory(COMPONENT_ESPRESSIF_ESP8266)
+endif()
 
-target_link_libraries(mbed-wifi
-    PUBLIC
-        mbed-rtos-flags
-        mbed-netsocket-api
-)

connectivity/drivers/wifi/esp8266-driver/CMakeLists.txt renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/CMakeLists.txt

@@ -6,7 +6,7 @@ The Mbed OS driver for the ESP8266 WiFi module.
 
 ESP8266 modules come in different shapes and formats, but the firmware version is the most important factor. To
 make sure that the firmware in your module is compatible with Mbed OS, follow the
-[Update guide](https://developer.mbed.org/teams/ESP8266/wiki/Firmware-Update).
+[Update guide](https://web.archive.org/web/20211025195109/https://os.mbed.com/teams/ESP8266/wiki/Firmware-Update).
 
 This driver supports AT firmware versions 1.3.0 to 1.7.0. We advise updating the
 [AT firmware](https://www.espressif.com/en/support/download/at?keys=) to at least version 1.7.0.

connectivity/drivers/wifi/esp8266-driver/ESP8266/ESP8266.cpp renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/ESP8266/ESP8266.cpp

@@ -2,5 +2,6 @@
 # SPDX-License-Identifier: Apache-2.0
 
 if("EMW3080B" IN_LIST MBED_TARGET_LABELS)
+    create_mbed_wifi_target()
     add_subdirectory(COMPONENT_EMW3080B EXCLUDE_FROM_ALL)
 endif()

connectivity/drivers/wifi/esp8266-driver/ESP8266/ESP8266.h renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/ESP8266/ESP8266.h

@@ -22,3 +22,5 @@ target_sources(mbed-wiced
     PRIVATE
         wiced_interface/default_wifi_interface.cpp
 )
+
+target_link_libraries(mbed-wifi PUBLIC mbed-wiced)

connectivity/drivers/wifi/esp8266-driver/ESP8266Interface.cpp renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/ESP8266Interface.cpp

@@ -13,4 +13,4 @@ target_include_directories(mbed-wio-emw3166
         .
 )
 
-target_link_libraries(mbed-wio-emw3166 INTERFACE mbed-wiced mbed-stm32f412xg)
+target_link_libraries(mbed-wio-emw3166 INTERFACE mbed-stm32f412xg)

connectivity/drivers/wifi/esp8266-driver/ESP8266Interface.h renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/ESP8266Interface.h

@@ -14,41 +14,53 @@
 
 // WiFI and WiFi/BT modules -----------------------------------------------------------
         "COMPONENT_43012": {
-            "description": "Infineon/Cypress AIROC Wifi/BT module",
+            "description": "Infineon/Cypress AIROC Wifi 802.11n (2.4GHz and 5GHz) + BT 5.4 module",
             "friendly_name": "Infineon CYW43012"
         },
         "COMPONENT_43438": {
-            "description": "Infineon/Cypress AIROC Wifi/BT module",
+            "description": "Infineon/Cypress AIROC Wifi 802.11n (2.4GHz) + BT 5.3 module",
             "friendly_name": "Infineon CYW43438"
         },
         "COMPONENT_4343W": {
-            "description": "",
-            "friendly_name": ""
+            "description": "Infineon/Cypress AIROC Wifi 802.11n (2.4GHz) + BT 5.3 module",
+            "friendly_name": "Infineon CYW4343W"
         },
         "COMPONENT_4343W_FS": {
-            "description": "",
-            "friendly_name": ""
+            "description": "Infineon/Cypress AIROC Wifi 802.11n (2.4GHz) + BT 5.3 module",
+            "friendly_name": "Infineon CYW4343W (Arduino Portenta variant)"
         },
         "COMPONENT_CYW43XXX": {
-            "description": "",
-            "friendly_name": ""
+            "description": "Generic component for Infineon/Cypress AIROC Wifi modules.  Add one of the specific part number components to get configs + firmware for your device.",
+            "friendly_name": "Infineon CYW43XXX"
+        },
+        "COMPONENT_WHD": {
+            "description": "Generic component for the driver for Infineon/Cypress wifi modules.  Works in combination with other components.",
+            "friendly_name": "Infineon Wifi Host Driver"
         },
+        // Annoyingly, STMicro wrote the driver for this module (since it is used on
+        // some of their dev boards), and they licensed it under terms that the 
+        // code may only run on STM32 chips.  So, this component is only available when
+        // an STMicro processor is in use.
         "COMPONENT_EMW3080B": {
-            "description": "",
-            "friendly_name": ""
+            "description": "Wifi 802.11b/g/n module (driver available for STM32 targets only)",
+            "friendly_name": "MXChip EMW3080B"
+        },
+        "COMPONENT_ESPRESSIF_ESP8266": {
+            "description": "Wifi 802.11b/g/n MCU running ESP8266-IDF-AT AT command firmware",
+            "friendly_name": "Espressif ESP8366"
         },
 
 // Bluetooth only modules -----------------------------------------------------------
         "COMPONENT_BlueNRG_2": {
-            "description": "",
-            "friendly_name": ""
+            "description": "STMicro BlueNRG-2",
+            "friendly_name": "STMicro BlueNRG-2"
         },
         "COMPONENT_BlueNRG_MS": {
-            "description": "",
-            "friendly_name": ""
+            "description": "Bluetooth 4.2 module",
+            "friendly_name": "STMicro BlueNRG-MS"
         },
 
-// Cellular modules -----------------------------------------------------------------
+// Cellular and Cellular/GNSS modules ----------------------------------------------
 		"COMPONENT_ALTAIR_ALT1250": {
             "description": "Cellular module from Altair",
             "friendly_name": "Altair ALT1250"
@@ -117,17 +129,32 @@
         },
         "COMPONENT_STM_S2_LP": {
         	"description": "802.15.4 module, present on X-Nucleo-S2868A1 board",
-            "friendly_name": "NXP/Freescale MCR20A"
+            "friendly_name": "STMicro S2-LP"
+        },
+
+// LoRa modules ---------------------------------------------------------------------
+		"COMPONENT_SX126x": {
+            "description": "LoRa Connect™ 150-960MHz Transcievers",
+            "friendly_name": "Semtech SX1272"
+        },
+		"COMPONENT_SX1272": {
+            "description": "LoRa Connect™ 860-1000MHz Transciever",
+            "friendly_name": "Semtech SX1272"
+        },
+		"COMPONENT_SX1276": {
+            "description": "LoRa Connect™ 137-1020MHz Transciever",
+            "friendly_name": "Semtech SX1276"
         },
 
 // Other ----------------------------------------------------------------------------
 
         "COMPONENT_CM0P_SECURE": {
-            "description": "Used on Cypress PSoC6 dual core processors.  When enabled, this activates the Cortex-M0 coprocessor in sleep mode.",
-            "friendly_name": "PSoC CM0 in Sleep Mode"
+        	"description": "Used on Cypress PSoC 64 dual core processors with secure boot.  When enabled, activates the Cortex-M0 coprocessor as a security coprocessor.",
+            
+            "friendly_name": "PSoC CM0 in Security Mode"
         },
         "COMPONENT_CM0P_SLEEP": {
-            "description": "Used on Cypress PSoC 64 dual core processors with secure boot.  When enabled, activates the Cortex-M0 coprocessor as a security coprocessor.",
+            "description": "Used on Cypress PSoC6 dual core processors.  When enabled, this activates the Cortex-M0 coprocessor in sleep mode.",
             "friendly_name": "PSoC CM0 in Sleep Mode"
         },
 
@@ -178,18 +205,11 @@
             "friendly_name": ""
         },
 
-        "COMPONENT_SX1276": {
-            "description": "",
-            "friendly_name": ""
-        },
+        
         "COMPONENT_TFM_S_FW": {
             "description": "",
             "friendly_name": ""
         },
-        "COMPONENT_WHD": {
-            "description": "",
-            "friendly_name": ""
-        },
         "COMPONENT_hm01b0": {
             "description": "320x320 monochrome camera module",
             "friendly_name": "Himax HM01B0"

connectivity/drivers/wifi/esp8266-driver/README.md renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/README.md

@@ -1982,6 +1982,7 @@
         ],
         "device_name": "STM32F412ZGTx"
     },
+    // Also known as MXChip EMW3166
     "WIO_EMW3166": {
         "inherits": [
             "MCU_STM32F412xG"

connectivity/drivers/wifi/esp8266-driver/mbed_lib.json renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/mbed_lib.json

@@ -40,12 +40,13 @@ class TargetNotFoundError(TargetAttributesError):
     """Target definition not found in targets.json."""
 
 
-def get_target_attributes(targets_json_data: dict, target_name: str) -> dict:
+def get_target_attributes(targets_json_data: dict, target_name: str, allow_non_public_targets: bool = False) -> dict:
     """Retrieves attribute data taken from targets.json for a single target.
 
     Args:
         targets_json_data: target definitions from targets.json
         target_name: the name of the target (often a Board's board_type).
+        allow_non_public_targets: If set to True, attributes can be gotten even for non-public targets
 
     Returns:
         A dictionary representation of the attributes for the target.
@@ -54,7 +55,7 @@ def get_target_attributes(targets_json_data: dict, target_name: str) -> dict:
         ParsingTargetJSONError: error parsing targets.json
         TargetNotFoundError: there is no target attribute data found for that target.
     """
-    target_attributes = _extract_target_attributes(targets_json_data, target_name)
+    target_attributes = _extract_target_attributes(targets_json_data, target_name, allow_non_public_targets)
     target_attributes["labels"] = get_labels_for_target(targets_json_data, target_name).union(
         _extract_core_labels(target_attributes.get("core", None))
     )
@@ -68,12 +69,13 @@ def get_target_attributes(targets_json_data: dict, target_name: str) -> dict:
     return target_attributes
 
 
-def _extract_target_attributes(all_targets_data: Dict[str, Any], target_name: str) -> dict:
+def _extract_target_attributes(all_targets_data: Dict[str, Any], target_name: str, allow_non_public_targets: bool) -> dict:
     """Extracts the definition for a particular target from all the targets in targets.json.
 
     Args:
         all_targets_data: a dictionary representation of the raw targets.json data.
         target_name: the name of the target.
+        allow_non_public_targets: If set to True, attributes can be gotten even for non-public targets
 
     Returns:
         A dictionary representation the target definition.
@@ -85,8 +87,8 @@ def _extract_target_attributes(all_targets_data: Dict[str, Any], target_name: st
         raise TargetNotFoundError(f"Target attributes for {target_name} not found.")
 
     # All target definitions are assumed to be public unless specifically set as public=false
-    if not all_targets_data[target_name].get("public", True):
-        raise TargetNotFoundError(f"Target attributes for {target_name} not found.")
+    if not all_targets_data[target_name].get("public", True) and not allow_non_public_targets:
+        raise TargetNotFoundError(f"Cannot get attributes for {target_name} because it is marked non-public in targets JSON.  This likely means you set MBED_TARGET to the name of the MCU rather than the name of the board.")
 
     target_attributes = get_overriding_attributes_for_target(all_targets_data, target_name)
     accumulated_attributes = get_accumulating_attributes_for_target(all_targets_data, target_name)

connectivity/drivers/wifi/esp8266-driver/nucleo_esp8266_hw_fc1.jpg renamed to connectivity/drivers/wifi/COMPONENT_ESPRESSIF_ESP8266/nucleo_esp8266_hw_fc1.jpg

@@ -21,7 +21,7 @@ def test_no_target_found(self):
             "Target_2": "some more attributes",
         }
         with self.assertRaises(TargetNotFoundError):
-            _extract_target_attributes(all_targets_data, "Unlisted_Target")
+            _extract_target_attributes(all_targets_data, "Unlisted_Target", False)
 
     def test_target_found(self):
         target_attributes = {"attribute1": "something"}
@@ -31,23 +31,26 @@ def test_target_found(self):
             "Target_2": "some more attributes",
         }
         # When not explicitly included public is assumed to be True
-        self.assertEqual(_extract_target_attributes(all_targets_data, "Target_1"), target_attributes)
+        self.assertEqual(_extract_target_attributes(all_targets_data, "Target_1", False), target_attributes)
 
     def test_target_public(self):
         all_targets_data = {
             "Target_1": {"attribute1": "something", "public": True},
             "Target_2": "some more attributes",
         }
         # The public attribute affects visibility but is removed from result
-        self.assertEqual(_extract_target_attributes(all_targets_data, "Target_1"), {"attribute1": "something"})
+        self.assertEqual(_extract_target_attributes(all_targets_data, "Target_1", False), {"attribute1": "something"})
 
     def test_target_private(self):
         all_targets_data = {
             "Target_1": {"attribute1": "something", "public": False},
             "Target_2": "some more attributes",
         }
         with self.assertRaises(TargetNotFoundError):
-            _extract_target_attributes(all_targets_data, "Target_1"),
+            _extract_target_attributes(all_targets_data, "Target_1", False)
+
+        # Should be able to get it if we pass the allow non public flag
+        self.assertEqual(_extract_target_attributes(all_targets_data, "Target_1", True), {"attribute1": "something"})
 
 
 class TestGetTargetAttributes(TestCase):
@@ -60,9 +63,9 @@ def test_gets_attributes_for_target(self, extract_core_labels, get_labels_for_ta
         build_attributes = {"attribute": "value"}
         extract_target_attributes.return_value = build_attributes
 
-        result = get_target_attributes(targets_json_data, target_name)
+        result = get_target_attributes(targets_json_data, target_name, False)
 
-        extract_target_attributes.assert_called_once_with(targets_json_data, target_name)
+        extract_target_attributes.assert_called_once_with(targets_json_data, target_name, False)
         get_labels_for_target.assert_called_once_with(targets_json_data, target_name)
         extract_core_labels.assert_called_once_with(build_attributes.get("core", None))
         self.assertEqual(result, extract_target_attributes.return_value)