1@page gpio GPIO
2
3[更正文档](https://gitee.com/alios-things/gpio/edit/master/README.md)      [贡献说明](https://help.aliyun.com/document_detail/302301.html)
4
5# 概述
6GPIO设备VFS驱动子系统。
7
8## 版权说明
9> Apache license v2.0
10
11## 目录结构
12```tree
13├── src
14│   └── gpio_dev.c          # HAL to VFS适配
15├── include
16│   └── aos
17│       ├── hal
18│       │   └── gpio.h      # HAL API
19│       └── vfsdev
20│           └── gpio_dev.h  # VFS API
21├── package.yaml            # 编译配置文件
22└── example
23    └── gpio_example.c      # 示例代码（默认禁用，可在package.yaml中使能）
24```
25
26## 依赖组件
27* base
28* vfs
29
30# 常用配置
31无
32
33# API说明
34
35## 打开
36```c
37int open(const char *pathname, int flags);
38```
39|args                                    |description|
40|:-----                                  |:----|
41|pathname                                |固定为`"/dev/gpio"`|
42|flags                                   |目前固定为0值|
43兼容POSIX标准的open接口。
44
45## 关闭
46```c
47int close(int fd);
48```
49兼容POSIX标准的close接口。
50
51## 配置输入属性并获取输入电平
52```c
53typedef struct gpio_io_config {
54    unsigned int id : 8;        // GPIO id
55    unsigned int config : 16;   // GPIO config
56    unsigned int data : 1;      // output data
57} gpio_io_config_t;
58
59int ioctl(int fd, IOC_GPIO_GET, gpio_io_config_t *config);
60```
61参数config中的id成员变量表示GPIO pin ID。
62参数config中的config成员变量表示输入属性：
63|符号                               |含义|
64|:-----                             |:----|
65|GPIO_IO_INPUT \| GPIO_IO_INPUT_PU  |输入上拉|
66|GPIO_IO_INPUT \| GPIO_IO_INPUT_PD  |输入下拉|
67|GPIO_IO_INPUT \| GPIO_IO_INPUT_HI  |输入高阻|
68参数config中的data成员变量无意义。
69返回值等于0表示输入为低电平，大于0表示输入为高电平，小于0表示出错。
70
71## 配置输出属性并设置输出电平
72```c
73int ioctl(int fd, IOC_GPIO_SET, gpio_io_config_t *config);
74```
75参数config中的id成员变量表示GPIO pin ID。
76参数config中的config成员变量表示输出属性：
77|符号                                   |含义|
78|:-----                                 |:----|
79|GPIO_IO_OUTPUT \| GPIO_IO_OUTPUT_PP    |输出推挽|
80|GPIO_IO_OUTPUT \| GPIO_IO_OUTPUT_ODNP  |输出开漏无上拉|
81|GPIO_IO_OUTPUT \| GPIO_IO_OUTPUT_ODPU  |输出开漏有上拉|
82|GPIO_IO_TOGGLE                         |翻转输出电平|
83参数config中的data成员变量表示输出电平，0表示低电平，1表示高电平；config为GPIO_IO_TOGGLE时data无意义。
84返回值等于0表示成功，小于0表示出错。
85
86## 配置中断
87```c
88typedef int (*io_irq_handler_t)(void *arg);
89
90typedef struct gpio_irq_config {
91    unsigned int id : 8;        // GPIO id
92    unsigned int config : 16;   // IRQ config
93    unsigned char *arg;         // IRQ callback argument
94    io_irq_handler_t cb;        // IRQ callback
95} gpio_irq_config_t;
96
97int ioctl(int fd, IOC_GPIO_SET_IRQ, gpio_irq_config_t *config);
98```
99参数config中的id成员变量表示GPIO pin ID。
100参数config中的config成员变量表示中断属性：
101|符号                                       |含义|
102|:-----                                     |:----|
103|GPIO_IRQ_ENABLE \| GPIO_IRQ_EDGE_RISING    |使能上升沿触发中断|
104|GPIO_IRQ_ENABLE \| GPIO_IRQ_EDGE_FALLING   |使能下降沿触发中断|
105|GPIO_IRQ_ENABLE \| GPIO_IRQ_EDGE_BOTH      |使能上升下降沿触发中断|
106|GPIO_IRQ_DISABLE                           |禁用中断|
107参数config中的cb成员变量表示中断回调函数。
108参数config中的arg成员变量表示传递给中断回调函数的参数。
109返回值等于0表示成功，小于0表示出错。
110
111# 使用示例
112组件使用示例相关的代码下载、编译和固件烧录均依赖AliOS Things配套的开发工具，所以首先需要参考[《AliOS Things集成开发环境使用说明之搭建开发环境》](https://help.aliyun.com/document_detail/302378.html)，下载安装。
113待开发环境搭建完成后，可以按照以下步骤进行示例的测试。
114
115## 步骤1 创建或打开工程
116
117**打开已有工程**
118
119如果用于测试的案例工程已存在，可参考[《AliOS Things集成开发环境使用说明之打开工程》](https://help.aliyun.com/document_detail/302381.html)打开已有工程。
120
121**创建新的工程**
122
123组件的示例代码可以通过编译链接到AliOS Things的任意案例（solution）来运行，这里选择helloworld_demo案例。helloworld_demo案例相关的源代码下载可参考[《AliOS Things集成开发环境使用说明之创建工程》](https://help.aliyun.com/document_detail/302379.html)。
124
125## 步骤2 添加组件
126
127案例下载完成后，需要在helloworld_demo组件的package.yaml中添加对组件的依赖：
128
129```yaml
130
131depends:
132  - gpio: master          # helloworld_demo中引入gpio组件
133
134```
135
136## 步骤3 下载组件
137
138在已安装了  的开发环境工具栏中，选择Terminal -> New Terminal启动终端，并且默认工作路径为当前工程的workspace，此时在终端命令行中输入：
139
140```shell
141
142aos install gpio
143
144```
145
146上述命令执行成功后，组件源码则被下载到了./components/drivers/peripheral路径中。
147
148## 步骤4 添加示例
149gpio组件的package.yaml中添加example
150```yaml
151source_file:
152  - "src/*.c"
153  - "example/gpio_example.c"
154```
155## 步骤5 编译固件
156
157在示例代码已经添加至组件的配置文件，并且helloworld_demo已添加了对该组件的依赖后，就可以编译helloworld_demo案例来生成固件了，具体编译方法可参考[《AliOS Things集成开发环境使用说明之编译固件》](https://help.aliyun.com/document_detail/302384.html)。
158
159## 步骤6 烧录固件
160
161helloworld_demo案例的固件生成后，可参考[《AliOS Things集成开发环境使用说明之烧录固件》](https://help.aliyun.com/document_detail/302383.html)来烧录固件。
162
163## 步骤7 打开串口
164
165固件烧录完成后，可以通过串口查看示例的运行结果，打开串口的具体方法可参考[《AliOS Things集成开发环境使用说明之查看日志》](https://help.aliyun.com/document_detail/302382.html)。
166
167当串口终端打开成功后，可在串口中输入help来查看已添加的测试命令。
168
169## 步骤8 测试示例
170CLI命令行输入：
171```
172gpiot <pin ID>
173```
174
175**关键日志**
176示例测试日志显示：
177```
178open gpio success, fd:<fd>
179gpio read <pin ID> return <ioctl IOC_GPIO_GET返回值>
180gpio write <pin ID> return <ioctl IOC_GPIO_SET（配置输出）返回值>
181gpio toggle <pin ID> return <ioctl IOC_GPIO_SET（翻转输出）返回值>
182```
183
184# 注意事项
185无
186
187# FAQ
1881. API中的pin ID如何填写？
189> 一般来说GPIO是分组的。以HaaS100为例，它的GPIO pin是8个一组。如果某GPIO pin名称为GPIO_2_6，则pin ID应为2 \* 8 + 6 = 22。其它pin ID的计算方法依此类推。
190