OSS-ECAL (called ˈiː kæl) is an abbreviation for Open Source Software for Electronic Components Abstraction Layer.
Background
Software for electronic components does not need to be newly developed for each electronic product because the functions of electronic components are pre-specified. In addition, software for electronic components is a non-competitive area that does not create a competitive advantage in electronic products, making it an unnecessary development cost. For this reason, product manufacturers are increasingly asking electronic component manufacturers to provide software for electronic components.
Purpose
The purpose of OSS-ECAL is to reduce development costs and improve quality for product manufacturers and electronic component manufacturers by promoting the common use of software for electronic components, a non-competitive area.
Features
OSS-ECAL is software with the following features.
1. Standard interfaces (APIs) for electronic components as software.
2. Interfaces (APIs) tailored to the characteristics of each electronic component.
3. Supports combinations of electronic components.
4. Wrapping each HAL.
5. Compatible with HAL from various MCU manufacturers.
Programming language: C programming language. In addition, the extension of OSS-ECAL for Mbed and Arduino has been changed to .cpp to match C++ programming language.
Definition of Terms
The definitions of terms and coding designations used in this document are shown in the table below.
| Term | Definition |
|---|---|
| ABC | Model number of electronic component temporary name |
| API | Application interface |
| c(prefix) | Const constant label name prefix |
| COMMAND | Command temporary name |
| e(prefix) | Enumerated type member-name prefix |
| et(prefix) | Enumerated type tag-name prefix |
| etCMP | OSS-ECAL common component code enum definition |
| etSTS | OSS-ECAL common status code enum definition |
| gv(prefix) | Global variables label name prefix |
| HAL | Hardware Abstraction Layer In AUTOSAR, MCAL |
| HALNAME | HAL temporary name Refer to the HAL correspondence table for HALNAME. |
| i(prefix) | Immediate constant label name prefix |
| o(prefix) | Command API function name prefix |
| OSS-ECAL | Open Source Software for Electronic Components Abstraction Layer |
| st(prefix) | Struct type label name prefix |
| sv(prefix) | Static variable label name prefix |
| tbl(prefix) | Table constants label name prefix |
| Component | Electronic component |
| SW Component | Software component |
API Function
Basic API Structure
The API is a command API function by electronic component model number and command as follows.
etSTS oABC_COMMAND( stABC_I, stABC_O* )
| Function name | oABC_COMMAND | API function name of ABC |
| Return value | etSTS | OSS-ECAL status code |
| Parameter IN | stABC_I | Input data of ABC function |
| Parameter OUT | stABC_O* | Output data of ABC function |
Command API Function Examples
The Byte Write command API function of Microchip Technology’s EEPROM 24xx256 series is introduced as an example.
etSTS o24xx256_BYTE_WRITE( etCMP cmp, uint16 mem_adr, uint8 val )
Process Overview:
The o24xx256_BYTE_WRITE function is an API function that writes the value of val to the specified address mem_adr for the 24xx256 series (24AA256, 24LC256, 24FC256). This function returns the return value eSTS_EXE until the time (i24xx256_WRITE_TIME [ms]) to complete writing has elapsed.
| Return value | etSTS | OSS-ECALステータスコード eSTS_FIN eSTS_EXE eSTS_ERR_PARAMETER eSTS_ERR_I2C_OBJECT eSTS_ERR_OTHERS_RUN eSTS_ERR_HAL_OTHERS_RUN eSTS_ERR_HAL_I2C | Completed successfully During execution parameter error（out of memory address range） I2C object selection error Other components are executing the process Other applications are running HAL HAL I2C error |
| Parameter IN | etCMP cmp | Common component code | e24xx256 20007U |
| uint16 mem_adr | Memory address | Range 0x0000 to 0x7fff | |
| uint8 val | Data to be written | Range 0x00 to 0xff |
Note:
The i24xx256_WRITE_TIME [ms] elapsed measurement is calculated from the Thread period that calls this function, so set the Thread period to THREAD_OSS_ECAL_PERIOD [ms]. When using this function, please use the o24xx256_WP_DIS function to release write-protection before using this function.
Reference:
The 24xx256 series also provides the following other command API functions.
etSTS o24xx256_PAGE_WRITE( etCMP cmp, uint16 mem_adr, uint16 len, uint8* buf )
The o24xx256_PAGE_WRITE function is an API function that writes the values buf[0] through buf[len-1] for the 24xx256 series (24AA256, 24LC256, 24FC256) in order from the specified address mem_adr. This function returns the return value eSTS_EXE until the time to complete the write (i24xx256_WRITE_TIME [ms]) has elapsed.
etSTS o24xx256_CURRENT_READ( etCMP cmp, uint8* rlt )
The o24xx256_CURRENT_READ function is an API function that reads the value of 1 byte from the last Read or Write address + 1 for the 24xx256 series (24AA256, 24LC256, 24FC256) and stores it in rlt.
etSTS o24xx256_RANDOM_READ( etCMP cmp, uint16 mem_adr, uint8* rlt )
The o24xx256_RANDOM_READ function is an API function that reads a 1-byte value from a specified address mem_adr for the 24xx256 series (24AA256, 24LC256, 24FC256) and stores it in rlt.
etSTS o24xx256_SEQ_READ( etCMP cmp, uint16 mem_adr, uint16 len, uint8* buf )
The o24xx256_SEQ_READ function is an API function that reads data for len from the specified address mem_adr for the 24xx256 series (24AA256, 24LC256, 24FC256) in sequence and stores the data from buf[0] to buf[len-1].
etSTS oAT24C08C_WP_EN( etCMP cmp )
The o24xx256_WP_EN function is an API function that outputs Write protect enable (write disable) = “Hi” for the 24xx256 series (24AA256, 24LC256, 24FC256).
etSTS oAT24C08C_WP_DIS( etCMP cmp )
The o24xx256_WP_DIS function is an API function that outputs Write protect disable (write enable) = “Low” for the 24xx256 series (24AA256, 24LC256, 24FC256).
HAL Support
OSS-ECAL’s HAL support is as follows (expanding sequentially). Please check each electronic component’s OSS-ECAL page for HAL support. Please note that even the same HAL may not work with different versions, MCUs, or development environments.
| Manufacturer | SDK/IDE Tool | HAL Name | Ver | Support |
|---|---|---|---|---|
| Arduino | Arduino IDE | Arduino | 1.8.6 | X |
| Arm | Keil MDK v6 | Mbed OS | 6.17.0 | X |
| Debian | – | GNU/Linux | 10.3 | – |
| Infineon | ModusToolbox | mtb-hal-cat1 | 2.4.3 | X |
| NXP | MCUXpresso SDK | SDK_2.x_EVKB-IMXRT1050 | 2.16 | X |
| STMicroelectronics | PlatformSDK_S32K1_2022_02 | AUTOSAR MCAL | 4.4 | – |
| Renesas | Synergy Software Package | HAL | 2.6.0 | – |
| STMicroelectronics | STM32Cube | STM32CubeF4 | V1.28.1 | X |
Development environment
The MCU and development environment during development are as follows.
| HAL Name | Manufacturer | Board | MCU | IDE |
|---|---|---|---|---|
| ARDUINO | Arduino | 1.Mega 2560 Rev3 2.Arduino Pro Mini 3.3V | ATmega2560 ATmega328P | Arduino IDE 2.3.3 |
| MBED | STMicroelectronics | STM32 Nucleo-64 boards | STM32F401RETx | Arm Keil Studio Cloud |
| Linux | BeagleBoard | BeagleBone Black | TI AM335x | – |
| ModusToolbox | Infineon | CY8CPROTO-063-BLE PSoC 6 BLE Prototyping Kit | CYBLE-416045-02 | ModusToolbox |
| iMXRT1051B1052B | NXP | IMXRT1050-EVKB | i.MX RT1050 | MCUXpresso IDE |
| MCAL | STMicroelectronics | S32K144EVB-Q100 | S32K144 | S32 Design Studio for S32 Platform |
| SSP | Renesas | S7G2 SK | R7FS7G27H3A01CFC | e² studio for Renesas Synergy |
| STM32F4 | STMicroelectronics | STM32 Nucleo-64 boards | STM32F401RETx | STM32CubeIDE |
File configuration
Please refer to the following example for the file structure of OSS-ECAL. The file structure differs depending on the HAL, so please check the OSS-ECAL page for each component.
Example: 24xx256 Folder structure
| Folder | File | Summary |
|---|---|---|
| 24xx256_IMXRT1050_010000/sample | sample.c | Sample application program |
| sample.h | Sample application header | |
| 24xx256_IMXRT1050_010000 | o24xx256.c | OSS-ECAL program for 24xx256 |
| o24xx256.h | OSS-ECAL header for 24xx256 | |
| oss_ecal.h | OSS-ECAL common header | |
| user_setting.c | User configured constants and tables | |
| user_setting.h | User configuration Header | |
| readme.md | Readme | |
| OSS-ECAL Terms of Use.txt | OSS-ECAL Terms of Use |
Built-in method
To incorporate command API functions into your product program, follow these steps.
- Obtaining the OSS-ECAL file
- Configure MCU and product program information
- Add command API functions to product program
- OSS-ECAL file added to product program development environment
1. Obtaining the OSS-ECAL file
Please inquire about downloading from the component page of the English OSS-ECAL site (https://oss-ecal.com/). The OSS-ECAL file (zip format) will be sent as an e-mail attachment to the e-mail address you specify.
Please unzip the sent file and remove the sample folder from the HAL folder to be used. Please use the files in the sample folder as reference code for incorporating into your application.
2. Configure MCU and product program information
This section explains how to embed OSS-ECAL based on the example of connecting one EEPROM 24xx256 series to an MCU (NXP i.MX RT1050). Match the code section in blue to the MCU or product program.
The MCU settings shown below are label names and circuit settings configured in the NXP MCUXpresso SDK.
1 Set the command API function cycle
Set the call cycle of the command API function in user_setting.h.
In this example, the cycle is 50ms.
<pre class="nohighlight">
// Immediate definitions
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#define THREAD_OSS_ECAL_PERIOD 50U // Thread period time[ms]2 Device address setting
The pin levels of A0, A1, and A2 pins of the 24xx256 series should be set in user_setting.h as shown in the following code.
In this example, A0 pin=Low(b0=0), A1 pin=Low(b1=0), A2 pin=Low(b2=0).
// Device address Code bit2:A2, bit1:A1, bit0:A0
#define M24xx256 0b00000000
// I2C components address
#define I2C_ADR_24xx256 (( 0b00001010 << 3 ) | ( 0x07 & M24xx256 ))3 Set the number of send/receive buffers
The number of send/receive buffers should be set in user_setting.h as shown in the code below. 24xx256 series has a maximum of 64Byte send/receive buffers.
In this example, the number of send buffers is 64Byte and the number of receive buffers is 64Byte.
// TX and RX buffer size(bytes) for 24xx256
// CAUTION : Set the minimum value among the following
// - Number of send/receive buffers used by the application
// - Number of send/receive buffers used by HAL
// - Number of 24xx256 send/receive Max 64 bytes
#define TX_N_24xx256 64U
#define RX_N_24xx256 64U4 MCU pin setting for write protect
The MCU GPIO pins connected to the write protect pin of the 24xx256 series should be set in user_setting.h as shown in the following code.
In this example, the write protect pin is connected to BOARD_INITPINS_M24xx256_WP_PIN on BOARD_INITPINS_M24xx256_WP_PORT.
// OSS-ECAL GPIO hard wiring
#define CMP_GPIO_NUM 1U // OSS-ECAL GPIO components number
#define GPIO_24xx256_WP BOARD_INITPINS_M24xx256_WP_PORT
#define PIN_24xx256_WP BOARD_INITPINS_M24xx256_WP_PIN5 I2C communication settings
The I2C to communicate with the 24xx256 series should be set in user_setting.h as shown in the following code.
In this example, the I2C communication LPI2C1_PERIPHERAL is connected, and the baud rate is set to 400 kHz.
In addition, one component using OSS-ECAL for I2C communication is assumed.
// OSS-ECAL I2C components hard wiring
#define CMP_I2C_NUM 1U
#define I2C_HZ 400000 // MCU I2C frequency
#define I2C_24xx256 LPI2C1_PERIPHERAL // LPI2C peripheral base address6 Set the number of I2C communication retries
The number of I2C communication retries should be set in user_setting.h as shown in the following code.
In this example, the I2C communication error is set to retry three times.
// I2C settings
#define I2C_RETRY 3U // Retry times7 Table setting for Device address and I2C
Set the device address set in 2 and the I2C set in 5 in user_setting.c as shown in the code below.
// HAL I2C object table for components
const stI2C_MCUX_OBJ tblI2C[ CMP_I2C_NUM ] =
{
{ e24xx256, I2C_ADR_24xx256, I2C_24xx256 }
};
8 Table setting of MCU pin for Write protect
Set the GPIO of write-protect set in 4 in user_setting.c as shown in the following code.
// HAL GPIO object table for components
const stGPIO_MCUX_OBJ tblGPIO[ CMP_GPIO_NUM ] =
{
{ e24xx256, GPIO_24xx256_WP, PIN_24xx256_WP }
};3. Add command API functions to product program
Refer to sample.c to add command API functions to your product program.
4. OSS-ECAL file added to product program development environment
Please add the OSS-ECAL file addition to your product program development environment.
5. Other ways to incorporate
How to incorporate multiple OSS-ECALs in a user program (same MCU function)
How to incorporate multiple OSS-ECALs in a user program (different MCU function)
How to incorporate multiple identical electronic components into a user program
How to reduce the impact on user programs by replacing electronic components
Points to note
Please use the OSS-ECAL in compliance with the OSS-ECAL Terms of Use. In addition, verification of electronic products is the responsibility of the product manufacturer.