 |
Cypress Mbed OS Documentation | ||
|
Cypress Mbed OS Documentation | ||
This article provides details on the firmware deliverables from Cypress in Mbed™ OS. Figure 1 shows the architecture of Mbed OS (Source: Mbed OS Documentation). For a general overview of Mbed OS, refer to the documentation at https://os.mbed.com/docs/.
This article provides details on relevant components highlighted in orange color in Figure 1 that are provided by Cypress. Specifically, the following firmware deliverables are covered:
Mbed OS provides a hardware abstraction layer (HAL) for the microcontrollers it runs on, so that developers can focus on writing C/C++ applications that call functionality available on a range of hardware. This includes drivers for common peripherals like Digital/Analog I/O pins, I2C, UART, SPI, Quad SPI, PWM, etc. See https://os.mbed.com/docs/mbed-os/latest/apis/drivers.html for details on using Driver APIs. See https://os.mbed.com/docs/mbed-os/latest/tutorials/index.html for examples for using driver APIs. Figure 2 shows how Cypress PSoC 6 MCU HAL, Mbed HAL, and Mbed OS drivers are related in an Mbed OS application.
The Peripheral Driver Library (PDL) simplifies software development for the PSoC 6 MCU architecture. PDL reduces the need to understand register usage and bit structures, thus easing software development for the extensive set of peripherals available. PDL contains no Mbed OS-specific information and should be usable in all RTOS environments. In Mbed OS, the PSoC 6 MCU PDL is present in the mbed-os\targets\TARGET_Cypress\ TARGET_PSOC6\psoc6pdl directory. The PDL documentation can be found at PSoC 6 PDL API Reference Manual.
PSoC 6 MCU HAL provides a high-level interface for interacting with PSoC 6 MCU peripherals. This interface abstracts chip-specific details. If any chip-specific functionality is necessary, or performance is critical, the low-level functions provided in PSoC 6 MCU PDL can be used directly. PSoC 6 MCU HAL is present in the mbed-os\targets\TARGET_Cypress\TARGET_PSOC6\psoc6csp directory.
To enable seamless porting of application code between different Arm® Cortex®-M-based devices, Mbed OS provides an Mbed HAL layer for using different peripherals. The Mbed HAL API (header files) is available in the \mbed-os\hal directory. The equivalent Mbed HAL API implementation (source files) for PSoC 6 MCU is provided by Cypress in the \mbed-os\targets\TARGET_Cypress\TARGET_PSOC6 directory. The Cypress implementation of the Mbed HAL relies mostly on the PSoC 6 MCU HAL APIs, and where necessary the PSoC 6 MCU PDL APIs.
Mbed OS provides a C++ wrapper for commonly used MCU peripherals and functionalities. These are available in the the \mbed-os\drivers directory.
In Mbed OS, a ‘target’ refers to the hardware development kit. Cypress provides the Target Implementation, also known as a Board Support Package (BSP), for all the Mbed OS-enabled kits from Cypress. Details of BSP are provided below.
The list of targets (BSPs) supported in Mbed OS by all the partners, and the respective target configurations is available in the file mbed-os\targets\targets.json. This file includes the Cypress targets supported in Mbed OS as well. For more information on the target configuration parameters in this file, see https://os.mbed.com/docs/mbed-os/latest/reference/adding-and-configuring-targets.html.
Cypress target BSPs are available in the \mbed-os\targets\TARGET_Cypress\TARGET_PSOC6 directory. Each target has a directory in the format TARGET_TARGETNAME. For example, CY8CKIT-062-WiFi-BT target folder is TARGET_CY8CKIT_062_WiFi_BT as shown in Figure 3.
BSP handles target hardware initialization code, configuration settings, startup code, linker scripts, etc. The information on BSP files provided in the target folder is specified in the table below.
|
Files, Folder in Target Implementation |
Details |
|
cybsp_target_name.c, cybsp_target_name.h |
Contains the Initialization function cybsp_init() for the target. This function initializes the on-board components like LEDs, buttons, and debug UART. |
|
cybsp_types.h |
Contains definitions for the on-board components like LEDs and buttons. These definitions are used in the BSP initialization code. |
|
design.modus file and Generated Source folder |
The design.modus file is used internally by BSP files for BSP configuration. It is responsible for holding the hardware configuration information of PSoC 6 MCU host as used on the target hardware. This file can be viewed, if needed, in the "Device Configurator" tool from ModusToolbox. The configuration files generated from design.modus are stored in the Generated Source folder. |
|
PinNames.h |
Contains the mapping of the on-board interfaces to the host MCU pins. Examples include LEDs, buttons, Arduino header pins, and I2C/UART/SPI interface pins. |
|
PeripheralNames.h |
Contains the mapping of the Mbed OS peripheral names to the PSoC 6 MCU functional block instances. This includes UART, SPI, I2C, PWM etc. |
|
PeripheralPins.c |
Contains the mapping of the PSoC 6 MCU Host pins, block instance name, and the specific functionality of the pin in relation to that block instance (Like P1[0] is mapped to UART_0 Instance, and serves as UART_RX pin). |
|
device folder |
Contains the startup code and linker scripts for different toolchains |
Cypress provides precompiled application images that are executed on Cortex M0+ core of the dual-CPU PSoC 6 MCU. These images are in the \mbed-os\targets\TARGET_Cypress\TARGET_PSOC6\psoc6cm0p folder. The images are provided as C arrays ready to be compiled as part of the Cortex M4 application. The Cortex M0+ application code is placed into the internal flash by the Cortex M4 linker script. The details of the different CM0+ image types are provided below.
Figure 4 shows the layers of the Wi-Fi and BLE protocol implementation in a PSoC 6 MCU and CYW43xxx based solution in Mbed OS.
The WLAN subsystem of CYW43xxx communicates with PSoC 6 MCU through the SDIO interface. SDIO interface consists of 6 signals – SDIO_CMD, SDIO_CLK, and SDIO_DATA[3:0]. The WLAN susbsytem on CYW43xxx includes the 802.11 physical layer (PHY) and the 802.11 Media Access Control (MAC) layer. The upper layers of the Wi-Fi protocol including the network stack, and the higher layer protocols (IP, TCP/UDP, HTTP, MQTT etc) are handled in PSoC 6 MCU.
The Bluetooth (BT) subsystem of CYW43xxx communicates with PSoC 6 MCU through the HCI UART interface with flow control enabled (TX, RX, RTS, CTS). The Bluetooth susbsytem on CYW43xxx implements the controller portion of the BLE stack which includes the radio and the link layer. The Host portion of the BLE stack, BLE profiles, and the application code reside on PSoC 6 MCU.
In addition to the SDIO and UART interfaces, there are also six control signals between the PSoC 6 MCU and CYW43xxx devices. These include the power control signals (WL_REG_ON, BT_REG_ON), CYW43xxx device wakeup signals (WL_DEV_WAKE, HOST_DEV_WAKE), and PSoC 6 MCU host wakeup signals (WL_HOST_WAKE, BT_HOST_WAKE). See the CYW43xxx device datasheet for details on these control signals, SDIO, and UART interfaces.
The following sections provide details on the Cypress firmware deliverables relevant to Wi-Fi and BLE.
Wi-Fi Host Driver (WHD) is the driver firmware running on the host MCU (PSoC 6 MCU) that uses the underlying communication interface (typically, but not restricted to, SDIO interface) to interface with the WLAN subsystem of the CYW43xxx device. WHD provides WLAN APIs which can be used by upper layers of the host MCU software framework. These include APIs for functionality such as scan, join, and SoftAP. Cypress provides the WHD firmware as part of Mbed OS in the mbed-os\targets\TARGET_Cypress\TARGET_PSOC6\TARGET_WHD folder.
In addition to the driver firmware, the WHD folder also contains other resources as listed below.
The WHD to Mbed Ethernet MAC (EMAC) driver interface is maintained in the mbed-os\features\netsocket\emac-drivers\TARGET_WHD folder. See https://os.mbed.com/docs/mbed-os/v5.13/porting/ethernet-port.html more details on the EMAC driver for WiFi.
Each board that supports Wi-Fi connectivity needs to be added to the mbed-os\features\lwipstack\mbed_lib.json file with appropriate settings. The LWIP stack settings for the Cypress kits with Wi-Fi functionality have been added to this file.
The application programming interface for IP networking is the Socket API. The Socket API relates to OSI layer 4, the transport layer. In Mbed OS, the Socket API is abstracted, and supports various protocols such as TCP and UDP. For information on Mbed OS Network Socket APIs, refer to https://os.mbed.com/docs/mbed-os/latest/apis/network-socket.html.
A socket requires a NetworkInterface instance to indicate which NetworkInterface the socket should be created on. The NetworkInterface provides a network stack that implements the underlying socket operations. NetworkInterface is also the controlling API that the application uses to specify the network configuration. For information on Mbed OS Network Interface APIs, refer to https://os.mbed.com/docs/mbed-os/latest/apis/network-interfaces.html.
CYW43xxx Wi-Fi/BT combo devices (CYW43012, CYW4343W) contain the dual-mode Bluetooth radio and controller functionality. The Bluetooth subsystem in these combo devices interface with a PSoC 6 MCU Host thorugh the HCI UART interface, and the BLE host stack runs on PSoC 6 MCU. Mbed OS does not support Classic Bluetooth. The abstraction layer between the Cypress BLE implementation and the Cordio BLE stack are located in mbed-os\features\FEATURE_BLE\targets\TARGET_Cypress.
Arm Mbed BLE, also called BLE_API, is the Bluetooth Low Energy software solution for Mbed OS. Developers can use it to create new BLE-enabled applications. Mbed OS’s BLE_API interfaces with the BLE controller on the platform. It hides the BLE stack’s complexity behind C++ abstractions and is compatible with all BLE-enabled Mbed platforms. For more information on the BLE APIs, see https://os.mbed.com/docs/mbed-os/latest/apis/ble.html.