lby/mr-library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

1.新增PWM文档。

Browse Source
This commit is contained in:
MacRsh
2024-01-19 02:18:40 +08:00
parent d80c8f1ca8
commit dffa5fba52
4 changed files with 572 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -141,13 +141,13 @@ int main(void)
| `I2C` | | | [√] | [√] |
| `Soft-I2C` | | | [√] | [√] |
| `Pin` | | | [√] | [√] |
| `PWM` | | [√] | | |
| `PWM` | | | [√] | [√] |
| `Serial` | | | [√] | [√] |
| `SPI` | | | [√] | [√] |
| `Timer` | | | [√] | [√] |
| `msh` | | | [√] | [√] |
| `LCD` | [√] | | | |
| `Senser` | [√] | | | |
| `msh` | | | [√] | [√] |
----------

4
README_EN.md
View File

@@ -152,13 +152,13 @@ the `Python` script automatically generates the configuration file.
| `I2C` | | | [√] | [√] |
| `Soft-I2C` | | | [√] | [√] |
| `Pin` | | | [√] | [√] |
| `PWM` | | [√] | | |
| `PWM` | | | [√] | [√] |
| `Serial` | | | [√] | [√] |
| `SPI` | | | [√] | [√] |
| `Timer` | | | [√] | [√] |
| `msh` | | | [√] | [√] |
| `LCD` | [√] | | | |
| `Senser` | [√] | | | |
| `msh` | | | [√] | [√] |
----------

282
document/device/pwm/pwm.md Normal file
View File

@@ -0,0 +1,282 @@
# PWM设备
[English](pwm_EN.md)
<!-- TOC -->
* [PWM设备](#pwm设备)
* [打开PWM设备](#打开pwm设备)
* [关闭PWM设备](#关闭pwm设备)
* [控制PWM设备](#控制pwm设备)
* [设置/获取通道编号](#设置获取通道编号)
* [设置/获取通道配置](#设置获取通道配置)
* [设置/获取频率](#设置获取频率)
* [读取PWM通道占空比](#读取pwm通道占空比)
* [写入PWM通道占空比](#写入pwm通道占空比)
* [使用示例：](#使用示例)
<!-- TOC -->
## 打开PWM设备
```c
int mr_dev_open(const char *name, int oflags);
```
| 参数 | 描述 |
|---------|---------|
| name | 设备名称 |
| oflags | 打开设备的标志 |
| **返回值** | |
| `>=0` | 设备描述符 |
| `<0` | 错误码 |
- `name`：PWM设备名称一般为：`pwmx`、`pwm1`、`pwm2`。
- `oflags`：打开设备的标志，支持 `MR_OFLAG_RDONLY`、 `MR_OFLAG_WRONLY`、 `MR_OFLAG_RDWR`。
注：使用时应根据实际情况为不同的任务分别打开PWM设备，并使用适当的`oflags`进行管理和权限控制，以确保它们不会相互影响。
## 关闭PWM设备
```c
int mr_dev_close(int desc);
```
| 参数 | 描述 |
|---------|-------|
| desc | 设备描述符 |
| **返回值** | |
| `=0` | 关闭成功 |
| `<0` | 错误码 |
注：关闭设备时所有的通道都将被自动恢复到默认配置，重新打开后需要重新配置通道（可关闭此功能）。
## 控制PWM设备
```c
int mr_dev_ioctl(int desc, int cmd, void *args);
```
| 参数 | 描述 |
|---------|-------|
| desc | 设备描述符 |
| cmd | 命令码 |
| args | 命令参数 |
| **返回值** | |
| `=0` | 设置成功 |
| `<0` | 错误码 |
- `cmd`：命令码，支持以下命令：
- `MR_CTL_PWM_SET_CHANNEL`：设置通道编号。
- `MR_CTL_PWM_SET_CHANNEL_CONFIG`：设置通道配置。
- `MR_CTL_PWM_SET_FREQ`：设置频率。
- `MR_CTL_PWM_GET_CHANNEL`：获取通道编号。
- `MR_CTL_PWM_GET_CHANNEL_CONFIG`：获取通道配置。
- `MR_CTL_PWM_GET_FREQ`：获取频率。
### 设置/获取通道编号
通道编号范围：`0` ~ `31`。
```c
/* 定义通道编号 */
#define CHANNEL_NUMBER 1
/* 设置通道编号 */
mr_dev_ioctl(ds, MR_CTL_PWM_SET_CHANNEL, MR_MAKE_LOCAL(int, CHANNEL_NUMBER));
/* 获取通道编号 */
int number;
mr_dev_ioctl(ds, MR_CTL_PWM_GET_CHANNEL, &number);
```
不依赖PWM接口：
```c
/* 定义通道编号 */
#define CHANNEL_NUMBER 1
/* 设置通道编号 */
mr_dev_ioctl(ds, MR_CTL_SET_OFFSET, MR_MAKE_LOCAL(int, CHANNEL_NUMBER));
/* 获取通道编号 */
int number;
mr_dev_ioctl(ds, MR_CTL_GET_OFFSET, &number);
```
### 设置/获取通道配置
通道配置：
- `MR_DISABLE`：禁用通道。
- `MR_ENABLE`：启用通道。
```c
struct mr_pwm_config config = {MR_ENABLE, MR_PWM_POLARITY_NORMAL};
/* 设置通道配置 */
mr_dev_ioctl(ds, MR_CTL_PWM_SET_CHANNEL_CONFIG, &config);
/* 获取通道配置 */
mr_dev_ioctl(ds, MR_CTL_PWM_GET_CHANNEL_CONFIG, &config);
```
不依赖PWM接口：
```c
int config[] = {MR_ENABLE, 0};
/* 设置通道配置 */
mr_dev_ioctl(ds, MR_CTL_SET_CONFIG, &config);
/* 获取通道配置 */
mr_dev_ioctl(ds, MR_CTL_GET_CONFIG, &config);
```
### 设置/获取频率
```c
/* 定义频率 */
#define PWM_FREQ 1000
/* 设置频率 */
mr_dev_ioctl(ds, MR_CTL_PWM_SET_FREQ, MR_MAKE_LOCAL(uint32_t, PWM_FREQ));
/* 获取频率 */
uint32_t freq;
mr_dev_ioctl(ds, MR_CTL_PWM_GET_FREQ, &freq);
```
不依赖PWM接口：
```c
/* 定义频率 */
#define PWM_FREQ 1000
/* 设置频率 */
mr_dev_ioctl(ds, (0x01 << 8), MR_MAKE_LOCAL(uint32_t, PWM_FREQ));
/* 获取频率 */
uint32_t freq;
mr_dev_ioctl(ds, (-(0x01 << 8)), &freq);
```
## 读取PWM通道占空比
```c
ssize_t mr_dev_read(int desc, void *buf, size_t size);
```
| 参数 | 描述 |
|---------|---------|
| desc | 设备描述符 |
| buf | 读取数据缓冲区 |
| size | 读取数据大小 |
| **返回值** | |
| `>=0` | 读取数据大小 |
| `<0` | 错误码 |
```c
/* 读取占空比 */
uint32_t duty;
int ret = mr_dev_read(ds, &duty, sizeof(duty));
/* 是否读取成功 */
if (ret != sizeof(duty))
{
return ret;
}
```
注：读取数据为PWM占空比，范围：`0` ~ `1000000`。单次读取最小单位为`uint32_t`，即4个字节。
## 写入PWM通道占空比
```c
ssize_t mr_dev_write(int desc, const void *buf, size_t size);
```
| 参数 | 描述 |
|---------|---------|
| desc | 设备描述符 |
| buf | 写入数据缓冲区 |
| size | 写入数据大小 |
| **返回值** | |
| `>=0` | 写入数据大小 |
| `<0` | 错误码 |
```c
/* 写入占空比 */
uint32_t duty = 500000;
int ret = mr_dev_write(ds, &duty, sizeof(duty));
/* 是否写入成功 */
if (ret != sizeof(duty))
{
return ret;
}
```
注：写入数据为PWM占空比，范围：`0` ~ `1000000`。单次写入最小单位为`uint32_t`，即4个字节。
## 使用示例：
```c
#include "include/mr_lib.h"
/* 定义通道编号和频率 */
#define CHANNEL_NUMBER 1
#define FREQ 1000
/* 定义PWM设备描述符 */
int pwm_ds = -1;
int pwm_init(void)
{
int ret = MR_EOK;
/* 初始化PWM */
pwm_ds = mr_dev_open("pwm1", MR_OFLAG_RDWR);
if (pwm_ds < 0)
{
mr_printf("PWM1 open failed: %s\r\n", mr_strerror(pwm_ds));
return pwm_ds;
}
/* 打印PWM描述符 */
mr_printf("PWM1 desc: %d\r\n", pwm_ds);
/* 设置到通道1 */
mr_dev_ioctl(pwm_ds, MR_CTL_PWM_SET_CHANNEL, MR_MAKE_LOCAL(int, CHANNEL_NUMBER));
/* 设置通道使能 */
ret = mr_dev_ioctl(pwm_ds, MR_CTL_PWM_SET_CHANNEL_CONFIG, MR_MAKE_LOCAL(struct mr_pwm_config, MR_ENABLE, MR_PWM_POLARITY_NORMAL));
if (ret < 0)
{
mr_printf("Channel1 enable failed: %s\r\n", mr_strerror(ret));
return ret;
}
ret = mr_dev_ioctl(pwm_ds, MR_CTL_PWM_SET_FREQ, MR_MAKE_LOCAL(uint32_t, FREQ));
if (ret < 0)
{
mr_printf("Freq configure failed: %s\r\n", mr_strerror(ret));
return ret;
}
return MR_EOK;
}
/* 导出到自动初始化（APP级） */
MR_INIT_APP_EXPORT(pwm_init);
int main(void)
{
/* 自动初始化（pwm_init函数将在此处自动调用） */
mr_auto_init();
while(1)
{
/* 写入占空比 */
uint32_t duty = 500000;
int ret = mr_dev_write(pwm_ds, &duty, sizeof(duty));
/* 是否写入成功 */
if (ret != sizeof(duty))
{
mr_printf("Write failed: %s\r\n", mr_strerror(ret));
return ret;
}
mr_delay_ms(1000);
}
}
```
PWM频率设置为1000Hz，通道1输出50%占空比。

286
document/device/pwm/pwm_EN.md Normal file
View File

@@ -0,0 +1,286 @@
# PWM Device
[中文](pwm.md)
<!-- TOC -->
* [PWM Device](#pwm-device)
* [Open PWM Device](#open-pwm-device)
* [Close PWM Device](#close-pwm-device)
* [Control PWM Device](#control-pwm-device)
* [Set/Get Channel Number](#setget-channel-number)
* [Set/Get Channel Configuration](#setget-channel-configuration)
* [Set/Get Frequency](#setget-frequency)
* [Read PWM Channel Duty Cycle](#read-pwm-channel-duty-cycle)
* [Write PWM Channel Duty Cycle](#write-pwm-channel-duty-cycle)
* [Example:](#example)
<!-- TOC -->
## Open PWM Device
```c
int mr_dev_open(const char *name, int oflags);
```
| Parameter | Description |
|------------------|-------------------------|
| name | Device name |
| oflags | Flag for opening device |
| **Return Value** | |
| `>=0` | Device descriptor |
| `<0` | Error code |
- `name`: PWM device name usually is: `pwmx`、`pwm1`、`pwm2`.
- `oflags`: Flag for opening device, support `MR_OFLAG_RDONLY`、 `MR_OFLAG_WRONLY`、 `MR_OFLAG_RDWR`.
Note: When using, the PWM device should be opened separately for different tasks with the appropriate `oflags`
for management and permission control, to ensure they will not interfere with each other.
## Close PWM Device
```c
int mr_dev_close(int desc);
```
| Parameter | Description |
|------------------|--------------------|
| desc | Device descriptor |
| **Return Value** | |
| `=0` | Close successfully |
| `<0` | Error code |
Note: When closing the device, all channels will be automatically restored to the default configuration.
The channels need to be reconfigured after reopening (can disable this feature).
## Control PWM Device
```c
int mr_dev_ioctl(int desc, int cmd, void *args);
```
| Parameter | Description |
|------------------|-------------------|
| desc | Device descriptor |
| cmd | Command code |
| args | Command parameter |
| **Return Value** | |
| `=0` | Set successfully |
| `<0` | Error code |
- `cmd`: Command code, support:
- `MR_CTL_PWM_SET_CHANNEL`: Set channel number.
- `MR_CTL_PWM_SET_CHANNEL_CONFIG`: Set channel configuration.
- `MR_CTL_PWM_SET_FREQ`: Set frequency.
- `MR_CTL_PWM_GET_CHANNEL`: Get channel number.
- `MR_CTL_PWM_GET_CHANNEL_CONFIG`: Get channel configuration.
- `MR_CTL_PWM_GET_FREQ`: Get frequency.
### Set/Get Channel Number
Channel number range: `0` ~ `31`.
```c
/* Define channel number */
#define CHANNEL_NUMBER 1
/* Set channel number */
mr_dev_ioctl(ds, MR_CTL_PWM_SET_CHANNEL, MR_MAKE_LOCAL(int, CHANNEL_NUMBER));
/* Get channel number */
int number;
mr_dev_ioctl(ds, MR_CTL_PWM_GET_CHANNEL, &number);
```
Independent of PWM interface:
```c
/* Define channel number */
#define CHANNEL_NUMBER 1
/* Set channel number */
mr_dev_ioctl(ds, MR_CTL_SET_OFFSET, MR_MAKE_LOCAL(int, CHANNEL_NUMBER));
/* Get channel number */
int number;
mr_dev_ioctl(ds, MR_CTL_GET_OFFSET, &number);
```
### Set/Get Channel Configuration
Channel configuration:
- `MR_DISABLE`: Disable channel.
- `MR_ENABLE`: Enable channel.
```c
struct mr_pwm_config config = {MR_ENABLE, MR_PWM_POLARITY_NORMAL};
/* Set channel configuration */
mr_dev_ioctl(ds, MR_CTL_PWM_SET_CHANNEL_CONFIG, &config);
/* Get channel configuration */
mr_dev_ioctl(ds, MR_CTL_PWM_GET_CHANNEL_CONFIG, &config);
```
Independent of PWM interface:
```c
int config[] = {MR_ENABLE, 0};
/* Set channel configuration */
mr_dev_ioctl(ds, MR_CTL_SET_CONFIG, &config);
/* Get channel configuration */
mr_dev_ioctl(ds, MR_CTL_GET_CONFIG, &config);
```
### Set/Get Frequency
```c
/* Define frequency */
#define PWM_FREQ 1000
/* Set frequency */
mr_dev_ioctl(ds, MR_CTL_PWM_SET_FREQ, MR_MAKE_LOCAL(uint32_t, PWM_FREQ));
/* Get frequency */
uint32_t freq;
mr_dev_ioctl(ds, MR_CTL_PWM_GET_FREQ, &freq);
```
Independent of PWM interface:
```c
/* Define frequency */
#define PWM_FREQ 1000
/* Set frequency */
mr_dev_ioctl(ds, (0x01 << 8), MR_MAKE_LOCAL(uint32_t, PWM_FREQ));
/* Get frequency */
uint32_t freq;
mr_dev_ioctl(ds, (-(0x01 << 8)), &freq);
```
## Read PWM Channel Duty Cycle
```c
ssize_t mr_dev_read(int desc, void *buf, size_t size);
```
| Parameter | Description |
|------------------|-------------------------|
| desc | Device descriptor |
| buf | Buffer for reading data |
| size | Size of reading data |
| **Return Value** | |
| `>=0` | Size of reading data |
| `<0` | Error code |
```c
/* Read duty cycle */
uint32_t duty;
int ret = mr_dev_read(ds, &duty, sizeof(duty));
/* Check if reading succeeds */
if (ret != sizeof(duty))
{
return ret;
}
```
Note: The reading data is PWM duty cycle, ranging from `0` to `1000000`.
The minimum unit for single reading is `uint32_t`, which is 4 bytes.
## Write PWM Channel Duty Cycle
```c
ssize_t mr_dev_write(int desc, const void *buf, size_t size);
```
| Parameter | Description |
|------------------|-------------------------|
| desc | Device descriptor |
| buf | Buffer for writing data |
| size | Size of writing data |
| **Return Value** | |
| `>=0` | Size of writing data |
| `<0` | Error code |
```c
/* Write duty cycle */
uint32_t duty = 500000;
int ret = mr_dev_write(ds, &duty, sizeof(duty));
/* Check if writing succeeds */
if (ret != sizeof(duty))
{
return ret;
}
```
Note: The writing data is PWM duty cycle, ranging from `0` to `1000000`.
The minimum unit for single writing is `uint32_t`, which is 4 bytes.
## Example:
```c
#include "include/mr_lib.h"
/* Define channel number and frequency */
#define CHANNEL_NUMBER 1
#define FREQ 1000
/* PWM device descriptor */
int pwm_ds = -1;
int pwm_init(void)
{
int ret = MR_EOK;
/* PWM initialization */
pwm_ds = mr_dev_open("pwm1", MR_OFLAG_RDWR);
if (pwm_ds < 0)
{
mr_printf("PWM1 open failed: %s\r\n", mr_strerror(pwm_ds));
return pwm_ds;
}
/* Print PWM descriptor */
mr_printf("PWM1 desc: %d\r\n", pwm_ds);
/* Set to channel 1*/
mr_dev_ioctl(pwm_ds, MR_CTL_PWM_SET_CHANNEL, MR_MAKE_LOCAL(int, CHANNEL_NUMBER));
/* Set channel enable */
ret = mr_dev_ioctl(pwm_ds, MR_CTL_PWM_SET_CHANNEL_CONFIG, MR_MAKE_LOCAL(struct mr_pwm_config, MR_ENABLE, MR_PWM_POLARITY_NORMAL));
if (ret < 0)
{
mr_printf("Channel1 enable failed: %s\r\n", mr_strerror(ret));
return ret;
}
ret = mr_dev_ioctl(pwm_ds, MR_CTL_PWM_SET_FREQ, MR_MAKE_LOCAL(uint32_t, FREQ));
if (ret < 0)
{
mr_printf("Freq configure failed: %s\r\n", mr_strerror(ret));
return ret;
}
return MR_EOK;
}
/* Export to automatic initialization (APP level) */
MR_INIT_APP_EXPORT(pwm_init);
int main(void)
{
/* Automatically initialize (pwm_init function will be automatically called here) */
mr_auto_init();
while(1)
{
/* Write duty cycle */
uint32_t duty = 500000;
int ret = mr_dev_write(pwm_ds, &duty, sizeof(duty));
/* Check if writing succeeds */
if (ret != sizeof(duty))
{
mr_printf("Write failed: %s\r\n", mr_strerror(ret));
return ret;
}
mr_delay_ms(1000);
}
}
```
The PWM frequency is set to 1000Hz, and channel 1 outputs 50% duty cycle.