介绍

OSS-ECAL（简称：ECAL）是指电子元件抽象化层的开源软件（Open Source Software for Electronic Components Abstraction Layer）的缩写。

背景

电子元件用程序由于电子元件的功能已预先确定规格，因此无需针对每种电子产品进行重新开发。此外，电子元件用软件属于电子产品中不具备竞争优势的非竞争领域，导致了不必要的开发成本。因此，嵌入式产品制造商对电子元件制造商提出提供电子元件用程序的需求日益增加。

1. 电子元件用程序的课题

1) 提供示例程序

电子元件制造商各社为销售促进目的投入大量成本、人力和时间开发样品程序。然而，嵌入式产品制造商虽可参考这些样品程序，但实际将其嵌入产品的案例并不多。

2) 非竞争领域的程序开发

电子元件制造商和嵌入式产品制造商各公司，在开发可共同使用的非竞争领域程序时，投入了大量成本、人力和时间。

3) 标准化进展缓慢的领域

电子元件用程序由于电子元件种类繁多，且与之配合的微控制器也种类繁多，因此标准化进程较为缓慢。此外，缺乏推动标准化的组织也是导致这一延迟的原因之一。

通过OSS-ECAL实现问题解决

OSS-ECAL可解决电子元件用程序所面临的以下问题。

解决方案

  • 根据电子元件的种类，通过标准API促进标准化
  • 考虑产品实施所需的可靠性和可维护性的设计
  • 支持多种电子元件的组合配置
  • 通过对HAL进行封装，实现对多种MCU的兼容性

编程语言：C。请注意，对于用于 Mbed 和 Arduino 的 OSS-ECAL，扩展名已改为 .cpp，以便与 C++ 匹配。

术语的定义

下表给出了本出版物中使用的术语和编码名称的定义。

用语内涵
ABC电子元件型号 暂定名称
API应用界面
c（前缀）常量常数标签名称的前缀
COMMAND指挥部暂定名
e（前缀）枚举型enum 成员名称前缀
et（前缀）枚举型enum 标签名称前缀
etCMPOSS-ECAL 通用电子元件代码枚举类型（enum）定义
etSTSOSS-ECAL 通用状态码枚举型（enum）定义
gv（前缀）全局变量的标签名称前缀
HALHardware Abstraction Layer, 在 AUTOSAR 中，MCAL
HALNAMEHAL 的暂定名称
关于 HALNAME，请参阅 HAL 支持
i（前缀）immediate 常量标签名称的前缀
o（前缀）命令 API 功能名称前缀
OSS-ECALOpen Source Software for Electronic Components Abstraction Layer
st（前缀）结构体struct标签名称的前缀
sv（前缀）静态变量标签名称的前缀
tbl（前缀）表格常量的标签名称前缀
Component电子零件
SW-Component软件组件

API

1. API 基本结构

API 是按电子元件型号和命令分列的命令 API 功能，如下所示。

etSTS oABC_COMMAND( stABC_I, stABC_O* )

函数名oABC_COMMANDABC 命令的 API 函数名称
返回类型etSTSOSS-ECAL 标准状态类型
参数 IN 的类型stABC_I参数的输入类型
参数 OUT的类型stABC_O*参数的输出类型

2. 命令 API 函数示例

以 Microchip Technology EEPROM 24xx256 系列的字节写入命令 API 功能为例。

etSTS o24xx256_BYTE_WRITE( etCMP cmp, uint16 mem_adr, uint8 val )

过程概述
o24xx256_BYTE_WRITE 函数是一个 API 函数，用于将 val 的值写入 24xx256 系列（24AA256、24LC256、24FC256）的指定地址 mem_adr。 函数返回返回值 eSTS_EXE，直到完成写入的时间（i24xx256_WRITE_TIME [ms]）过去。

返回类型etSTSOSS-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
正常终止
执行期间
参数错误（超出内存地址范围）
I2C对象选择错误
其他组件正在执行程序
其他应用程序正在运行 HAL
HAL I2C错误
参数 IN 的类型etCMP cmp通用电子元件代码e24xx256　20007U
uint16 mem_adr内存地址范围0x0000 to 0x7fff
uint8 val要写入的数据范围0x00 to 0xff

备注
i24xx256_WRITE_TIME [ms] 已用测量值是通过调用此函数的Thread周期计算得出的，因此应将线程周期设置为 THREAD_OSS_ECAL_PERIOD [ms]。 使用此函数时，请使用 o24xx256_WP_DIS 函数在使用前解除写保护。

参考
24xx256 系列可使用以下其他命令 API 功能。

etSTS o24xx256_PAGE_WRITE( etCMP cmp, uint16 mem_adr, uint16 len, uint8* buf )
o24xx256_PAGE_WRITE 函数是一个 API 函数，用于从 24xx256 系列（24AA256、24LC256、24FC256）的指定地址 mem_adr 依次写入 buf[0] 至 buf[len-1] 的值。 函数返回返回值 eSTS_EXE，直到完成写入的时间（i24xx256_WRITE_TIME [ms]）已过。

etSTS o24xx256_CURRENT_READ( etCMP cmp, uint8* rlt )
o24xx256_CURRENT_READ 函数是一个 API 函数，用于从 24xx256 系列（24AA256、24LC256、24FC256）的最后一个读或写地址 + 1 中读取 1 个字节的值并将其存储到 rlt 中。

etSTS o24xx256_RANDOM_READ( etCMP cmp, uint16 mem_adr, uint8* rlt )
o24xx256_RANDOM_READ 函数是一个 API 函数，用于从 24xx256 系列（24AA256、24LC256、24FC256）的指定地址 mem_adr 中读取一个字节的值并将其存储到 rlt 中。

etSTS o24xx256_SEQ_READ( etCMP cmp, uint16 mem_adr, uint16 len, uint8* buf )
o24xx256_SEQ_READ 函数是一个 API 函数，用于从 24xx256 系列（24AA256、24LC256、24FC256）的指定地址 mem_adr 依次读取 len 的数据，并将其从 buf[0] 保存到 buf[len-1]。

etSTS o24xx256_WP_EN( etCMP cmp )
o24xx256_WP_EN 函数是一个 API 函数，用于输出 24xx256 系列（24AA256、24LC256、24FC256）的写保护启用（写禁用）=“Hi”。

etSTS o24xx256_WP_DIS( etCMP cmp )
o24xx256_WP_DIS 函数是一个 API 函数，用于输出 24xx256 系列（24AA256、24LC256、24FC256）的写保护禁用（写使能）=“Low”。

HAL 支持

OSS-ECAL 的 HAL 支持如下（逐步扩展）。
请查看各电子元件的 OSS-ECAL 页面，了解 HAL 支持情况。 请注意，即使使用相同的 HAL，不同的版本、MCU 和开发环境也可能无法以相同的方式运行。

ManufacturerSDK/IDE ToolHAL NameVerHALNAMESupport
ArduinoArduino IDEArduino1.8.6ARDUINOX
ArmKeil MDK v6Mbed OS6.17.0MBEDX
Debian–GNU/Linux10.3Linux–
InfineonModusToolboxmtb-hal-cat12.4.3ModusToolboxX
NXPMCUXpresso SDKSDK_2.x_EVKB-IMXRT10502.16iMXRT1051B1052BX
RenesasSynergy Software PackageHAL2.6.0SSP–
STMicroelectronicsSTM32CubeSTM32CubeF4V1.28.1STM32F4X

1. 开发环境

开发过程中的 MCU 和开发环境如下。

HAL NameManufacturerBoardMCUIDE
ARDUINOArduino1.Mega 2560 Rev3
2.Arduino Pro Mini 3.3V		ATmega2560
ATmega328P		Arduino IDE 2.3.3
MBEDSTMicroelectronicsSTM32 Nucleo-64 boardsSTM32F401RETxArm Keil Studio Cloud
LinuxBeagleBoardBeagleBone BlackTI AM335x–
ModusToolboxInfineonCY8CPROTO-063-BLE PSoC 6 BLE Prototyping KitCYBLE-416045-02ModusToolbox
iMXRT1051B1052BNXPIMXRT1050-EVKBi.MX RT1050MCUXpresso IDE
SSPRenesasS7G2 SKR7FS7G27H3A01CFCe² studio for Renesas Synergy
STM32F4STMicroelectronicsSTM32 Nucleo-64 boardsSTM32F401RETxSTM32CubeIDE

文件配置

有关 OSS-ECAL 的文件结构，请参阅下面的示例。 文件结构因 HAL 而异，请查看各组件的 OSS-ECAL 页面。

例如：24xx256 文件夹结构

FolderFileSummary
24xx256_IMXRT1050_010000/samplesample.cSample application program
sample.hSample application header
24xx256_IMXRT1050_010000o24xx256.cOSS-ECAL program for 24xx256
o24xx256.hOSS-ECAL header for 24xx256
oss_ecal.hOSS-ECAL common header
user_setting.cUser configured constants and tables
user_setting.hUser configuration Header
readme.mdReadme
OSS-ECAL Terms of Use.txtOSS-ECAL Terms of Use

内置方法

要在产品程序中加入命令 API 功能，请按照以下步骤操作。

  1. 获取 OSS-ECAL 文件
  2. 配置 MCU 和产品程序信息
  3. 为产品程序添加命令 API 功能
  4. 在产品程序开发环境中添加 OSS-ECAL 文件

1. 获取 OSS-ECAL 文件

请从英文版 OSS-ECAL 网站 (https://oss-ecal.com/) 的组件页面咨询下载事宜。 OSS-ECAL 文件（zip 格式）将作为电子邮件附件发送到您指定的电子邮件地址。

请解压缩发送的文件，并从要使用的 HAL 文件夹中删除样本文件夹。 请将样本文件夹中的文件用作参考代码，以便纳入您的应用程序。

2. 配置 MCU 和产品程序信息

本节以将一个 EEPROM 24xx256 系列连接到 MCU（NXP i.MX RT1050）为例，说明如何嵌入 OSS-ECAL。 将蓝色代码部分与 MCU 或产品程序匹配。

下面显示的 MCU 设置是在 NXP MCUXpresso SDK 中配置的标签名称和电路设置。

1) 设置命令 API 功能周期

设置 user_setting.h 中命令 API 函数的调用周期。
在本例中，周期为 50 毫秒。

<pre class="nohighlight">
// Immediate definitions
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#define THREAD_OSS_ECAL_PERIOD  50U     // Thread period time[ms]
2) 设备地址设置

24xx256 系列的 A0、A1 和 A2 引脚电平应在 user_setting.h 中设置，如以下代码所示。

在本例中，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) 设置发送/接收缓冲区的数量

发送/接收缓冲区的数量应在 user_setting.h 中设置，如下所示。 24xx256 系列的发送/接收缓冲区最大为 64 字节。
在本例中，发送缓冲区的数量为 64 Byte，接收缓冲区的数量为 64 Byte。

// 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            64U
4) 用于写保护的 MCU 引脚设置

连接到 24xx256 系列写保护引脚的 MCU GPIO 引脚应在 user_setting.h 中设置，如以下代码所示。
在本例中，写保护引脚连接到 BOARD_INITPINS_M24xx256_WP_PORT 上的 BOARD_INITPINS_M24xx256_WP_PIN 上。

// 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_PIN
5) I2C 通信设置

与 24xx256 系列通信的 I2C 应在 user_setting.h 中设置，如以下代码所示。
在本例中，连接了 I2C 通信 LPI2C1_PERIPHERAL，波特率设置为 400 kHz。
此外，假定有一个组件使用 OSS-ECAL 进行 I2C 通信。

// 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 address
6) 设置 I2C 通信重试次数

I2C 通信重试次数应在 user_setting.h 中设置，如以下代码所示。
在本例中，I2C 通信错误被设置为重试三次。

// I2C settings
#define I2C_RETRY               3U      // Retry times
7) 设备地址和 I2C 的表格设置

如下代码所示，在 user_setting.c 中将设备地址设置为 2)，将 I2C 设置为 5)。

// HAL I2C object table for components
const stI2C_MCUX_OBJ tblI2C[ CMP_I2C_NUM ] =
{
        { e24xx256, I2C_ADR_24xx256, I2C_24xx256 }
};
8) 用于写保护的 MCU 引脚表设置

在 user_setting.c 中设置写保护的 GPIO，设置值为 4)，如以下代码所示。

// HAL GPIO object table for components
const stGPIO_MCUX_OBJ tblGPIO[ CMP_GPIO_NUM ] =
{
        { e24xx256, GPIO_24xx256_WP, PIN_24xx256_WP }
};

3. 为产品程序添加命令 API 功能

请参阅 sample.c，将命令 API 函数添加到产品程序中。

4. 在产品程序开发环境中添加 OSS-ECAL 文件

请将 OSS-ECAL 文件添加到您的产品程序开发环境中。

5. 其他纳入方式

如何将 OSS-ECAL 纳入用户程序

如何在用户程序中整合多个 OSS-ECAL（相同的 MCU 功能）

如何在用户程序中整合多个 OSS-ECAL（不同 MCU 功能）

如何将多个相同的电子元件整合到一个用户程序中

如何通过更换电子元件减少对用户程序的影响

注意事项

请按照 OSS-ECAL 使用条款使用 OSS-ECAL。 此外，电子产品的验证由产品制造商负责。

OSS-ECAL Chinese
error: 内容受保护 !