From a2889f5e23f76e12f51efd5bc64bc69348d8344c Mon Sep 17 00:00:00 2001 From: WildboarG <959586@outlook.com> Date: Wed, 19 Feb 2025 11:29:38 +0800 Subject: [PATCH 01/17] add docs --- docs/_coverpage.md | 15 ++ docs/_media/logo.svg | 38 +++ docs/_navbar.md | 6 + docs/en-us/.nojekyll | 0 docs/en-us/README.md | 55 ++++ docs/en-us/_sidebar.md | 23 ++ docs/en-us/adc.md | 346 ++++++++++++++++++++++++ docs/en-us/bluetooth.md | 117 ++++++++ docs/en-us/dac.md | 240 +++++++++++++++++ docs/en-us/flash.md | 272 +++++++++++++++++++ docs/en-us/gpio.md | 251 +++++++++++++++++ docs/en-us/guide.md | 16 ++ docs/en-us/iic.md | 289 ++++++++++++++++++++ docs/en-us/pwm.md | 224 ++++++++++++++++ docs/en-us/rng.md | 46 ++++ docs/en-us/rtc.md | 207 ++++++++++++++ docs/en-us/spi.md | 223 ++++++++++++++++ docs/en-us/timer.md | 152 +++++++++++ docs/en-us/uart.md | 579 ++++++++++++++++++++++++++++++++++++++++ docs/en-us/wdg.md | 87 ++++++ docs/en-us/wifi.md | 505 +++++++++++++++++++++++++++++++++++ docs/index.html | 46 ++++ docs/zh-cn/.nojekyll | 0 docs/zh-cn/README.md | 3 + docs/zh-cn/_sidebar.md | 5 + docs/zh-cn/guide.md | 4 + 26 files changed, 3749 insertions(+) create mode 100644 docs/_coverpage.md create mode 100644 docs/_media/logo.svg create mode 100644 docs/_navbar.md create mode 100644 docs/en-us/.nojekyll create mode 100644 docs/en-us/README.md create mode 100644 docs/en-us/_sidebar.md create mode 100644 docs/en-us/adc.md create mode 100644 docs/en-us/bluetooth.md create mode 100644 docs/en-us/dac.md create mode 100644 docs/en-us/flash.md create mode 100644 docs/en-us/gpio.md create mode 100644 docs/en-us/guide.md create mode 100644 docs/en-us/iic.md create mode 100644 docs/en-us/pwm.md create mode 100644 docs/en-us/rng.md create mode 100644 docs/en-us/rtc.md create mode 100644 docs/en-us/spi.md create mode 100644 docs/en-us/timer.md create mode 100644 docs/en-us/uart.md create mode 100644 docs/en-us/wdg.md create mode 100644 docs/en-us/wifi.md create mode 100644 docs/index.html create mode 100644 docs/zh-cn/.nojekyll create mode 100644 docs/zh-cn/README.md create mode 100644 docs/zh-cn/_sidebar.md create mode 100644 docs/zh-cn/guide.md diff --git a/docs/_coverpage.md b/docs/_coverpage.md new file mode 100644 index 000000000..cce7f70ea --- /dev/null +++ b/docs/_coverpage.md @@ -0,0 +1,15 @@ +![logo](_media/logo.svg) + +# AI-Thinker-WB2入门指南 latest + +> API指南来自于安信可科技. + + + +[GitHub](https://github.com/Ai-Thinker-Open/Ai-Thinker-WB2.git) +[Get Started](/en-us/README.md) diff --git a/docs/_media/logo.svg b/docs/_media/logo.svg new file mode 100644 index 000000000..2c1a0e83c --- /dev/null +++ b/docs/_media/logo.svg @@ -0,0 +1,38 @@ + + + + +Created by potrace 1.15, written by Peter Selinger 2001-2017 + + + + + diff --git a/docs/_navbar.md b/docs/_navbar.md new file mode 100644 index 000000000..bbeaf07b0 --- /dev/null +++ b/docs/_navbar.md @@ -0,0 +1,6 @@ +* [主页](/) +* Language + * [En](/en-us/README.md) + * [简体中文](/zh-cn/README.md) + + diff --git a/docs/en-us/.nojekyll b/docs/en-us/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/docs/en-us/README.md b/docs/en-us/README.md new file mode 100644 index 000000000..d5d0516d4 --- /dev/null +++ b/docs/en-us/README.md @@ -0,0 +1,55 @@ +## 快速入门 + +本文档旨在指导用户搭建 Ai-WB2 系列硬件开发的软件环境，通过一个简单的示例展示如何使用安信可提供的代码框架进行编译、下载固件至开发板等步骤。 + + + +Ai-WB2系列模组 + +- 2.4 Gz Wi-Fi + +- 高性能 32 位 RISC-V 单核处理器 + +- 多种外设 + +- 支持 IEEE 802.11 b/g/n 协议 + +- Wi-Fi安全支持WPS/WEP/WPA/WPA2 Personal/WPA2 Enterprise/WPA3 + +- 支持20MHz带宽，最高速率 72.2 Mbps + +- Bluetooth 低能耗5.0，Bluetooth Mesh + +- 支持 Station + BLE模式、Station + SoftAP + BLE模式 + +- 支持32-bit RISC CPU，276KB RAM + +- 安全启动，支持使用ECC-256签名的镜像 + +- 支持QSPI/SPI Flash即时AES解密（OTFAD）,支持AES 128 CTR模式 + +- 支持AES 128/192/256位加密引擎 + +- 支持SHA-1/224/256 + +- 支持真实随机数发生器 (TRNG) + +- 公钥加速器 (PKA), 支持大数基本运算, 软件提供签名，验证等应用程序接口 + +- 支持SDIO，SPI，UART，I2C，IR remote，PWM，ADC，DAC，PIR，GPIO等 + +- 集成 Wi-Fi MAC/BB/RF/PA/LNA/BT + +- 支持多种休眠模式，深度睡眠电流12μA + +- 通用AT指令可快速上手 + +- 支持二次开发，集成了Windows、Linux开发环境 + + + +## Ai-WB2系列环境搭建 + +1. Linux环境搭建请参考： Ai-WB2系列模组[linux开发环境搭建](https://blog.csdn.net/Boantong_/article/details/125604649?ops_request_misc=%257B%2522request%255Fid%2522%253A%2522166617877716800182741996%2522%252C%2522scm%2522%253A%252220140713.130102334.pc%255Fblog.%2522%257D&request_id=166617877716800182741996&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2~blog~first_rank_ecpm_v1~rank_v31_ecpm-3-125604649-null-null.nonecase&utm_term=wb2&spm=1018.2226.3001.4450) +2. window环境搭建请参考： Ai-WB2系列的[eclipes搭建环境教程](https://bbs.ai-thinker.com/forum.php?mod=viewthread&tid=45149&ctid=23) + diff --git a/docs/en-us/_sidebar.md b/docs/en-us/_sidebar.md new file mode 100644 index 000000000..1a9dcd4c8 --- /dev/null +++ b/docs/en-us/_sidebar.md @@ -0,0 +1,23 @@ +* :shamrock: Quick start + * [Start](/en-us/README.md) +* :orange_book: Guide Book + * [Guide](/en-us/guide.md "The greatest guide in the world") +* :clap: API + * :ghost: WIFI + * [Wifi](/en-us/wifi.md) + * :fountain: BLUETOOTH + * [Bluetooth](/en-us/bluetooth.md) + * :tractor: Peripherals + * [GPIO](/en-us/gpio.md) + * [UART](/en-us/uart.md) + * [ADC](/en-us/adc.md) + * [DAC](/en-us/dac.md) + * [IIC](/en-us/iic.md) + * [PWM](/en-us/pwm.md) + * [RNG](/en-us/rng.md) + * [RTC](/en-us/rtc.md) + * [SPI](/en-us/spi.md) + * [TIMER](/en-us/timer.md) + * [WDG](/en-us/wdg.md) + * :ballot_box: Storage + * [FLASH](/en-us/flash.md) diff --git a/docs/en-us/adc.md b/docs/en-us/adc.md new file mode 100644 index 000000000..610e82084 --- /dev/null +++ b/docs/en-us/adc.md @@ -0,0 +1,346 @@ +# ADC API指南 + +## 概述 + +模数转换器（analog-to-digital converter，通常称为ADC）是一种模拟与数字转换器，支持12路外部模拟输入和若干内部模拟信号选择。 ADC支持以下四种模式：单次单通道转换、连续单通道转换、单次多通道转换和连续多通道转换模式。 转换结果为12/14/16bits左对齐模式。ADC拥有深度为32的FIFO，支持多种中断和DMA操作。 ADC除了用于普通模拟信号测量外，还可以用于测量供电电压， 此外ADC还可以通过测量内/外部二极管电压用于温度检测。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_adc.h + +#### Functions + +```c +int hosal_adc_init(hosal_adc_dev_t *adc) +``` + +Initialises an ADC interface, Prepares an ADC hardware interface for sampling. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the interface which should be initialised + + + +```c +int hosal_adc_add_channel(hosal_adc_dev_t *adc, uint32_t channel) +``` + +Add a channel to an ADC interface. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the interface which should be sampled +> - channel: adc channel + + + +```c +int hosal_adc_remove_channel(hosal_adc_dev_t *adc, uint32_t channel) +``` + +Remove a channel to an ADC interface. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the interface which should be sampled +> - channel: adc channel + + + +```c +hosal_adc_dev_t *hosal_adc_device_get(void) +``` + +Takes adc device handle from an ADC interface. + +> `return` +> +> - other get adc device success +> - NULL if an error occurred with any step + + + +```c +int hosal_adc_value_get(hosal_adc_dev_t *adc, uint32_t channel, uint32_t timeout) +``` + +Takes a single sample from an ADC interface. + +> `return` +> +> - other get adc data success +> - -1 if an error occurred with any step +> +> `Parameters` +> +> - adc: the interface which should be sampled +> - channel: adc channel +> - timeout: ms timeout + + + +```c +int hosal_adc_tsen_value_get(hosal_adc_dev_t *adc) +``` + +Takes a tsen sample from an ADC interface. + +> `return` +> +> - other get adc data success +> - -1 if an error occurred with any step +> +> `Parameters` +> +> - adc: the interface which should be sampled + + + +```c +int hosal_adc_sample_cb_reg(hosal_adc_dev_t *adc, hosal_adc_cb_t cb) +``` + +ADC sampling cb register. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the ADC interface +> - cb: Non-zero pointer is the sample callback handler NULL pointer for send unregister operation adc in cb must be the same pointer with adc pointer passed to hosal_adc_sample_cb_reg driver must notify upper layer by calling cb if ADC data is ready in HW or memory(DMA) + + + +```c +int hosal_adc_start(hosal_adc_dev_t *adc, void *data, uint32_t size) +``` + +ADC sampling start. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the ADC interface +> - data: adc data buffer +> - size: data buffer size aligned with resolution (until the next power of two) + + + +```c +int hosal_adc_stop(hosal_adc_dev_t *adc) +``` + +ADC sampling stop. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the ADC interface + + + +```c +int hosal_adc_finalize(hosal_adc_dev_t *adc) +``` + +De-initialises an ADC interface, Turns off an ADC hardware interface. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the interface which should be de-initialised + + + +#### Structures + +```c +struct hosal_adc_data_t +``` + +ADC data type. + +- `uint32_t size` + + sampled data size + +- `void *data` + + sampled data, aligned with resolution (until the next power of two) + +```c +struct hosal_adc_config_t +``` + +Define ADC config args. + +> Public Members +> +> - `uint32_t sampling_freq` +> +> sampling frequency in Hz +> +> - `uint32_t pin` +> +> adc pin +> +> - `hosal_adc_sample_mode_t mode` +> +> adc sampling mode +> +> - `uint8_t sample_resolution` +> +> adc sampling resolution + +```c +struct hosal_adc_dev_t +``` + +Define ADC dev hosal handle. + +> Public Members +> +> - `uint8_t port` +> +> adc port +> +> - `hosal_adc_config_t config` +> +> adc config +> +> - `hosal_dma_chan_t dma_chan` +> +> adc dma channel +> +> - `hosal_adc_irq_t cb` +> +> adc callback +> +> - `void *p_arg` +> +> p_arg data +> +> - `void *priv` +> +> priv data + +#### Macros + +```c +HOSAL_WAIT_FOREVER +``` + +Define the wait forever timeout macro. + +```c +TIMER_RELOAD_ONCE +``` + +timer reload once and need to reload manually + +#### Type Definitions + +```c +typedef enum __ADC_INT_EVENTS__ hosal_adc_event_t +``` + +ADC interrupt events. + +```c +typedef void (*hosal_adc_irq_t)(void *parg) +``` + +ADC interrupt function. + +- `Parameters` + + parg: Set the custom parameters specified + +```c +typedef void (*hosal_adc_cb_t)(hosal_adc_event_t event, void *data, uint32_t size) +``` + +ADC interrupt callback. + +- `Parameters` + + parg: Set the custom parameters specified when the callback function is set + +#### Enumerations + +```c +enum __ADC_INT_EVENTS__ +``` + +ADC interrupt events. + +Values: + +- `HOSAL_ADC_INT_OV` + + Overrun error. + +- `HOSAL_ADC_INT_EOS` + + End of sample. + +- `HOSAL_ADC_INT_DMA_TRH` + + DMA transceive half. + +- `HOSAL_ADC_INT_DMA_TRC` + + DMA transceive complete. + +- `HOSAL_ADC_INT_DMA_TRE` + + @briefDMA transceive error + +```c +enum hosal_adc_sample_mode_t +``` + +ADC MODE type. + +Values: + +- `HOSAL_ADC_ONE_SHOT` + + Single time sampling. + +- `HOSAL_ADC_CONTINUE` + + Continuous sampling. \ No newline at end of file diff --git a/docs/en-us/bluetooth.md b/docs/en-us/bluetooth.md new file mode 100644 index 000000000..7c4814a91 --- /dev/null +++ b/docs/en-us/bluetooth.md @@ -0,0 +1,117 @@ +# 蓝牙 API指南 + +------ + +## API参考 + +### Functions + +controller层初始化 + +```c +void ble_controller_init(uint8_t task_priority) +``` + +- `Parameters` + + - task_priority 任务优先级 + +- `return` + + ​ 无 + +HCI接口驱动初始化 + +```c +int hci_driver_init(void) +``` + +- `Parameters` +- `return` + +ble使能 + +```c +int bt_enable(bt_ready_cb_t cb) +``` + +- `Parameters` + - cb：如果成功调用回调函数 +- `return` + - 0:成功， != 0:失败 + +开启BLE扫描 + +```c +int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb) +``` + +- `Parameters` + + - param: 指向广播配置参数指针 cb: 扫描回调函数 + +- `return` + + - 0:成功， != 0:失败 + + + +停止BLE扫描 + +```c +int bt_le_scan_stop(void) +``` + +- `Parameters` +- `return` + - 0:成功， != 0:失败 + + + +设置连接安全等级 + +```c +int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec) +``` + +- `Parameters` + - conn:指向连接对象的指针 sec:安全等级 +- `return` + - 0:成功， != 0:失败 + + + +注册连接回调函数 + +```c +void bt_conn_cb_register(struct bt_conn_cb *cb) +``` + +- `Parameters` + - conn:指向连接对象的指针 +- `return` 无 + + + +注册认证回调函数 + +```c +int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb) +``` + +- `Parameters` + - cb：回调函数指针 +- `return` + - 0:成功， != 0:失败 + + + +设置/清除SMP配对请求/响应数据认证需求中的绑定标志 + +```c +void bt_set_bondable(bool enable) +``` + +- `Parameters` + - enable： 1，使能，0：不使能 +- `return` 无 \ No newline at end of file diff --git a/docs/en-us/dac.md b/docs/en-us/dac.md new file mode 100644 index 000000000..e7978d51d --- /dev/null +++ b/docs/en-us/dac.md @@ -0,0 +1,240 @@ +## DAC + +### 概述 + +数模转换器（digital-to-analog converter，通常称为DAC）是一种数字与模拟转换器，，FIFO深度为1，支持2路DAC调制输出。 可用于音频播放，常规的模拟信号调制。 + +### API参考 + +#### Header File + +components/platform/hosal/include/hosal_dac.h + +#### Functions + +```c +int hosal_dac_init(hosal_dac_dev_t *dac) +``` + +Initialises an dac interface. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - dac: the interface which should be initialised + + + +```c +int hosal_dac_finalize(hosal_dac_dev_t *dac) +``` + +De-initialises an dac interface, Turns off an dac hardware interface. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - dac: the interface which should be de-initialised + + + +```c +int hosal_dac_start(hosal_dac_dev_t *dac) +``` + +Start output dac （no DMA mode） + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - dac: the interface which should be started + + + +```c +int hosal_dac_stop(hosal_dac_dev_t *dac) +``` + +Stop output dac. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - dac: the interface which should be stopped + + + +```c +int hosal_dac_set_value(hosal_dac_dev_t *dac, uint32_t data) +``` + +Output a value to an dac interface. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - dac: the interface to set value +> - data: the value to output, output unit: μV + + + +```c +int hosal_dac_get_value(hosal_dac_dev_t *dac) +``` + +Returns the last data output value of the selected dac channel. + +> `return` +> +> - dac output value, output unit: μV +> +> `Parameters` +> +> - dac: the interface to get value + + + +```c +int hosal_dac_dma_cb_reg(hosal_dac_dev_t *dac, hosal_dac_cb_t callback, void *arg) +``` + +DAC cb register. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - dac: the DAC interface +> - callback: callback handler +> - arg: callback arg + + + +```c +int hosal_dac_dma_start(hosal_dac_dev_t *dac, uint32_t *data, uint32_t size) +``` + +DAC use DMA mode. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - adc: the DAC interface +> - data: dac data buffer +> - size: data buffer size + + + +```c +int hosal_dac_dma_stop(hosal_dac_dev_t *dac) +``` + +Stop output dac. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - dac: the interface which should be stopped + + + +#### Structures + +```c +struct hosal_dac_config_t +``` + +This struct define dac config args. + +> Public Members +> +> - `uint8_t dma_enable` +> +> 1: use dma, 0: no dma +> +> - `uint32_t pin` +> +> dac pin +> +> - `uint32_t freq` +> +> dac freq + + + +```c +struct hosal_dac_dev_t +``` + +This struct define dac device type. + +> Public Members +> +> - `uint8_t port` +> +> dac id +> +> - `hosal_dac_config_t config` +> +> dac config +> +> - `hosal_dac_cb_t cb` +> +> dma callback +> +> - `hosal_dma_chan_t dma_chan` +> +> dac dma channel +> +> - `void *arg` +> +> arg data +> +> - `void *priv` +> +> priv data + + + +#### Type Definitions + +```c +typedef void (*hosal_dac_cb_t)(void *arg) +``` + +hosal dac callback + +> - `Parameters` +> +> arg: Set the custom parameters specified when the callback function is set \ No newline at end of file diff --git a/docs/en-us/flash.md b/docs/en-us/flash.md new file mode 100644 index 000000000..91d827c5c --- /dev/null +++ b/docs/en-us/flash.md @@ -0,0 +1,272 @@ +# Flash API指南 + +## 概述 + +SDK中使用分区表保存flash各区的信息，包括引导程序、各种应用程序二进制文件、数据及文件系统等。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_flash.h + +#### Functions + +```c +hosal_flash_dev_t *hosal_flash_open(const char *name, unsigned int flags) +``` + +Open a flash partition device. + +`return` + +- NULL flash open error +- otherwise is flash partition device + +`Parameters` + +- name: flash partition name +- flags: flash flags - HOSAL_FLASH_FLAG_ADDR_0 - HOSAL_FLASH_FLAG_ADDR_1 - HOSAL_FLASH_FLAG_BUSADDR + + + +```c +int hosal_flash_info_get(hosal_flash_dev_t *p_dev, hosal_logic_partition_t *partition) +``` + +Get the information of the specified flash area. + +`Return` + +- 0 On success +- otherwise is error + +`Parameters` + +- p_dev: The target flash logical partition device +- partition: The buffer to store partition info + + + +```c +int hosal_flash_erase(hosal_flash_dev_t *p_dev, uint32_t off_set, uint32_t size) +``` + +Erase an area on a Flash logical partition. + +`Note` + +Erase on an address will erase all data on a sector that the address is belonged to, this function does not save data that beyond the address area but in the affected sector, the data will be lost. + +`return` + +- 0 On success + +- otherwise is error + +`Parameters` + +- p_dev: The target flash logical partition which should be erased +- off_set: Start address of the erased flash area +- size: Size of the erased flash area + + + +```c +int hosal_flash_write(hosal_flash_dev_t *p_dev, uint32_t *off_set, const void *in_buf, uint32_t in_buf_size) +``` + +Write data to an area on a flash logical partition without erase. + +`return` + +- 0 On success +- otherwise is error + +`Parameters` + +- p_dev: The target flash logical partition which should be read which should be written +- [in/out]: off_set Point to the start address that the data is written to, and point to the last unwritten address after this function is returned, so you can call this function serval times without update this start address. +- in_buf: point to the data buffer that will be written to flash +- in_buf_size: The size of the buffer + + + +```c +int hosal_flash_erase_write(hosal_flash_dev_t *p_dev, uint32_t *off_set, const void *in_buf, uint32_t in_buf_size) +``` + +Write data to an area on a flash logical partition with erase first. + +`return` + +- 0 On success +- otherwise is error + +`Parameters` + +- p_dev: The target flash logical partition which should be read which should be written +- [in/out]: off_set Point to the start address that the data is written to, and point to the last unwritten address after this function is returned, so you can call this function serval times without update this start address. +- in_buf: point to the data buffer that will be written to flash +- in_buf_size: The length of the buffer + + + +```c +int hosal_flash_read(hosal_flash_dev_t *p_dev, uint32_t *off_set, void *out_buf, uint32_t out_buf_size) +``` + +Read data from an area on a Flash to data buffer in RAM. + +`return` + +- 0 On success +- otherwise is error + +`Parameters` + +- p_dev: The target flash logical partition which should be read +- [in/out]: off_set Point to the start address that the data is read, and point to the last unread address after this function is returned, so you can call this function serval times without update this start address. +- out_buf: Point to the data buffer that stores the data read from flash +- out_buf_size: The length of the buffer + + + +```c +int hosal_flash_close(hosal_flash_dev_t *p_dev) +``` + +Close a flash partition device. + +`return` + +- 0 On success +- otherwise is error + +`Parameters` + +- p_dev: flash partition device + + + +```c +int hosal_flash_raw_read(void *buffer, uint32_t address, uint32_t length) +``` + +Read data from a row address on a Flash to data buffer in RAM. + +`return` + +- 0 On success +- otherwise is error + +`Parameters` + +- buffer: Point to the data buffer that stores the data read from flash +- address: Address on flash to read from +- length: Length (in bytes) of data to read + + + +```c +int hosal_flash_raw_write(void *buffer, uint32_t address, uint32_t length) +``` + +Write data to a row address on a Flash. + +`return` + +- 0 On success +- otherwise is error + +`Parameters` + +- buffer: Point to the data buffer that will be written to flash +- address: Address on flash to write to +- length: Length (in bytes) of data to write + + + +```c +int hosal_flash_raw_erase(uint32_t start_addr, uint32_t length) +``` + +Erase a region of the flash. + +`return` + +- 0 On success +- otherwise is error + +`Parameters` + +- start_addr: Address to start erasing flash. +- length: Length of region to erase. + +#### Structures + +```c +struct hosal_flash_dev +``` + +Hal flash partition device. + +> Public Members +> +> - `void *flash_dev` +> +> flash device + +```c +struct hosal_logic_partition_t +``` + +Hal flash partition manage struct. + +​ Public Members + +- `const char *partition_description` + + name + +- `uint32_t partition_start_addr` + + start addr + +- `uint32_t partition_length` + + length + +- `uint32_t partition_options` + + options + +#### Macros + +```c +HOSAL_FLASH_FLAG_ADDR_0 +``` + +Open flash prtition address 0 in prtition table. + +```c +HOSAL_FLASH_FLAG_ADDR_1 +``` + +Open flash prtition address 1 in prtition table. + +```c +HOSAL_FLASH_FLAG_BUSADD +``` + +Open the partition table and use the bus physical address of flash. (If it is not set, the offset address set in the partition table is used by default.) + + + +#### Type Definitions + +```c +typedef struct hosal_flash_dev hosal_flash_dev_t +``` + +Hal flash partition device. \ No newline at end of file diff --git a/docs/en-us/gpio.md b/docs/en-us/gpio.md new file mode 100644 index 000000000..b4d764f50 --- /dev/null +++ b/docs/en-us/gpio.md @@ -0,0 +1,251 @@ +# GPIO API指南 + +## 概述 + +通用型之输入输出（General-purpose input/output，通常称为GPIO），GPIO管理功能提供GPIO控制寄存器，实现软件对 GPIO 属性的配置，使用户能够方便地操作 GPIO。每个GPIO可以配置为输入、输出和可选功能三种模式。在每个模式下(除模拟可选功能)，提供设置上拉，下拉，浮空三种端口状态，此外GPIO还提供中断功能，可以配置为上升沿触发，下降沿触发或者高电平/低电平触发。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_gpio.h + +#### Functions + +```c +int hosal_gpio_init(hosal_gpio_dev_t *gpio) +``` + +Initialises a GPIO pin. + +Prepares a GPIO pin for use. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> gpio: the gpio pin which should be initialised + + + +```c +int hosal_gpio_output_set(hosal_gpio_dev_t *gpio, uint8_t value) +``` + +Set GPIO output high or low. + +> `Note` +> +> > Using this function on a gpio pin which is set to input mode is undefined. +> +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - gpio: the gpio pin which should be set +> - value: 0 : output low | >0 : output high + + + +```c +int hosal_gpio_input_get(hosal_gpio_dev_t *gpio, uint8_t *value) +``` + +Get the state of an input GPIO pin. Using this function on a gpio pin which is set to output mode will return an undefined value. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - gpio: the gpio pin which should be read +> - value: gpio value + + + +```c +int hosal_gpio_irq_set(hosal_gpio_dev_t *gpio, hosal_gpio_irq_trigger_t trigger_type, hosal_gpio_irq_handler_t handler, void *arg) +``` + +Enables an interrupt trigger for an input GPIO pin. Using this function on a gpio pin which is set to output mode is undefined. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - gpio: the gpio pin which will provide the interrupt trigger +> - trigger: the type of trigger (rising/falling edge or both) +> - handler: a function pointer to the interrupt handler +> - arg: an argument that will be passed to the interrupt handler + + + +```c +int hosal_gpio_irq_mask(hosal_gpio_dev_t *gpio, uint8_t mask) +``` + +Clear an interrupt status for an input GPIO pin. Using this function on a gpio pin which has generated a interrupt. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - gpio: the gpio pin which provided the interrupt trigger +> - mask: 0 : mask | 1 : umask + + + +```c +int hosal_gpio_finalize(hosal_gpio_dev_t *gpio) +``` + +Set a GPIO pin in default state. + +​ `return` + +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - gpio: the gpio pin which should be deinitialised + + + +#### Structures + +```c +struct hosal_gpio_ctx +``` + +hosal gpio ctx, use for multi gpio irq + +```c +struct hosal_gpio_dev_t +``` + +GPIO dev struct. + +> Public Members +> +> - `uint8_t port` +> +> gpio port +> +> - `hosal_gpio_config_t config` +> +> gpio config +> +> - `void *priv` +> +> priv data + + + +#### Type Definitions + +```c +typedef void (*hosal_gpio_irq_handler_t)(void *arg) +``` + +GPIO interrupt callback handler. + +> `Parameters` +> +> - parg: ：Set the custom parameters specified + + + +```c +typedef struct hosal_gpio_ctx hosal_gpio_ctx_t +``` + +hosal gpio ctx, use for multi gpio irq + + + +#### Enumerations + +```c +enum hosal_gpio_config_t +``` + +gpio config struct + +Values: + +> `ANALOG_MODE` + +Used as a function pin, input and output analog. + +> `INPUT_PULL_UP` + +Input with an internal pull-up resistor - use with devices that actively drive the signal low - e.g. button connected to ground. + +> `INPUT_PULL_DOWN` + +Input with an internal pull-down resistor - use with devices that actively drive the signal high - e.g. button connected to a power rail. + +> `INPUT_HIGH_IMPEDANCE` + +Input - must always be driven, either actively or by an external pullup resistor. + +> `OUTPUT_PUSH_PULL` + +Output actively driven high and actively driven low - must not be connected to other active outputs - e.g. LED output. + +`OUTPUT_OPEN_DRAIN_NO_PULL` + +Output actively driven low but is high-impedance when set high - can be connected to other open-drain/open-collector outputs. Needs an external pull-up resistor. + +> `OUTPUT_OPEN_DRAIN_PULL_UP` + +Output actively driven low and is pulled high with an internal resistor when set high - can be connected to other open-drain/open-collector outputs. + +> `OUTPUT_OPEN_DRAIN_AF` + +Alternate Function Open Drain Mode. + +> `OUTPUT_PUSH_PULL_AF` + +Alternate Function Push Pull Mode. + + + +```c +enum hosal_gpio_irq_trigger_t +``` + +GPIO interrupt trigger. + +Values: + +> `HOSAL_IRQ_TRIG_NEG_PULSE` +> +> GPIO negedge pulse trigger interrupt. +> +> `HOSAL_IRQ_TRIG_POS_PULSE` +> +> GPIO posedge pulse trigger interrupt. +> +> `HOSAL_IRQ_TRIG_NEG_LEVEL` +> +> GPIO negedge level trigger interrupt (32k 3T) +> +> `HOSAL_IRQ_TRIG_POS_LEVEL` +> +> GPIO posedge level trigger interrupt (32k 3T) diff --git a/docs/en-us/guide.md b/docs/en-us/guide.md new file mode 100644 index 000000000..bfd906076 --- /dev/null +++ b/docs/en-us/guide.md @@ -0,0 +1,16 @@ +# hello +--- + +> just something 2025-02-15 19:31 + + +```c +#include + +int main(void){ + printf("hello world\r\n"); + return 0; +} +``` +``` +``` diff --git a/docs/en-us/iic.md b/docs/en-us/iic.md new file mode 100644 index 000000000..e68b39427 --- /dev/null +++ b/docs/en-us/iic.md @@ -0,0 +1,289 @@ +# I2C API指南 + +------ + +## I2C API + +### 概述 + +I2C (Inter-Intergrated Circuit)是一种串行通讯总线，使用多主从架构，用来连接低速外围装置。 每个器件都有一个唯一的识别地址，并且都可以作为一个发送器或接收器。 如果有两个或多个主机同时初始化，数据传输可以通过冲突检测和仲裁防止数据被破坏。 BL602/BL604包含一个I2C控制器主机，可灵活配置slaveAddr、subAddr以及传输数据，方便与从设备通信，提供2个word深度的fifo，提供中断功能，可搭配DMA使用提高效率，可灵活调整时钟频率。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_i2c.h + +#### Functions + +```c +int hosal_i2c_init(hosal_i2c_dev_t *i2c) +``` + +Initialises an I2C interface. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: the device for which the i2c port should be initialised + + + +```c +int hosal_i2c_master_send(hosal_i2c_dev_t *i2c, uint16_t dev_addr, const uint8_t *data, uint16_t size, uint32_t timeout) +``` + +I2c master send. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: the i2c device +> - dev_addr: device address +> - data: i2c send data +> - size: i2c send data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + + + +```c +int hosal_i2c_master_recv(hosal_i2c_dev_t *i2c, uint16_t dev_addr, uint8_t *data, uint16_t size, uint32_t timeout) +``` + +I2c master recv. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: the i2c device +> - dev_addr: device address +> - data: i2c receive data +> - size: i2c receive data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + + + +```c +int hosal_i2c_slave_send(hosal_i2c_dev_t *i2c, const uint8_t *data, uint16_t size, uint32_t timeout) +``` + +I2c slave send. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: the i2c device +> - data: i2c slave send data +> - size: i2c slave send data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + + + +```c +int hosal_i2c_slave_recv(hosal_i2c_dev_t *i2c, uint8_t *data, uint16_t size, uint32_t timeout) +``` + +I2c slave receive. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: tthe i2c device +> - data: i2c slave receive data +> - size: i2c slave receive data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + + + +```c +int hosal_i2c_mem_write(hosal_i2c_dev_t *i2c, uint16_t dev_addr, uint32_t mem_addr, uint16_t mem_addr_size, const uint8_t *data, uint16_t size, uint32_t timeout) +``` + +I2c mem write. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: the i2c device +> - dev_addr: device address +> - mem_addr: mem address +> - mem_addr_size: mem address +> - data: i2c master send data +> - size: i2c master send data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + + + +```c +int hosal_i2c_mem_read(hosal_i2c_dev_t *i2c, uint16_t dev_addr, uint32_t mem_addr, uint16_t mem_addr_size, uint8_t *data, uint16_t size, uint32_t timeout) +``` + +I2c master mem read. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: the i2c device +> - dev_addr: device address +> - mem_addr: mem address +> - mem_addr_size: mem address +> - data: i2c master send data +> - size: i2c master send data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + + + +```c +int hosal_i2c_finalize(hosal_i2c_dev_t *i2c) +``` + +Deinitialises an I2C device. + +> `return` +> +> - 0 on success +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - i2c: the i2c device + + + +#### Structures + +```c +struct hosal_i2c_config_t +``` + +I2C configuration. + +> Public Members +> +> - `uint32_t address_width` +> +> Addressing mode: 7 bit or 10 bit. +> +> - `uint32_t freq` +> +> CLK freq. +> +> - `uint8_t scl` +> +> i2c clk pin +> +> - `uint8_t sda` +> +> i2c data pin +> +> - `uint8_t mode` +> +> master or slave mode + +```c +structhosal_i2c_dev_t +``` + +I2C device type. + +> Public Members +> +> - `uint8_t port` +> +> i2c port +> +> - `hosal_i2c_config_t config` +> +> i2c config +> +> - `void *priv` +> +> priv data + + + + + +#### Macros + +```c +HOSAL_WAIT_FOREVER +``` + +Define the wait forever timeout macro. + +```c +HOSAL_I2C_MODE_MASTER +``` + +i2c communication is master mode + +```c +HOSAL_I2C_MODE_SLAVE +``` + +i2c communication is slave mode + +```c +HOSAL_I2C_MEM_ADDR_SIZE_8BIT +``` + +i2c memory address size 8bit + +```c +HOSAL_I2C_MEM_ADDR_SIZE_16BIT +``` + +i2c memory address size 16bit + +```c +HOSAL_I2C_MEM_ADDR_SIZE_24BIT +``` + +i2c memory address size 24bit + +```c +HOSAL_I2C_MEM_ADDR_SIZE_32BIT +``` + +i2c memory address size 32bit + +```c +HOSAL_I2C_ADDRESS_WIDTH_7BIT +``` + +7 bit mode + +```c +HOSAL_I2C_ADDRESS_WIDTH_10BIT +``` + +10 bit mode \ No newline at end of file diff --git a/docs/en-us/pwm.md b/docs/en-us/pwm.md new file mode 100644 index 000000000..88df1f215 --- /dev/null +++ b/docs/en-us/pwm.md @@ -0,0 +1,224 @@ +### PWM API指南 + +概述 + +脉冲宽度调制（Pulse width modulation，简称PWM）是一种模拟控制方式，根据相应载荷的变化来调制晶体管基极或MOS管栅极的偏置，来实现晶体管或MOS管导通时间的改变，从而实现开关稳定电源输出的改变。这种方式能使电源的输出电压在工作条件变化时保持恒定，是利用微处理器的数字信号对模拟电路进行控制的一种非常有效的技术，广泛应用在从测量、通信到功率控制与变换的许多领域中。 + +API参考 + +#### Header File + +```shel +components/platform/hosal/include/hosal_pwm.h +``` + +#### Functions + +```c +int hosal_pwm_init(hosal_pwm_dev_t *pwm) +``` + +Initialises a PWM pin. + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device + + + +```c +int hosal_pwm_start(hosal_pwm_dev_t *pwm) +``` + +Starts Pulse-Width Modulation signal output on a PWM pin. + + + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device + + + + + +```c +int hosal_pwm_stop(hosal_pwm_dev_t *pwm) +``` + +Stops output on a PWM pin. + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device + + + + + +```c +int hosal_pwm_para_chg(hosal_pwm_dev_t *pwm, hosal_pwm_config_t para) +``` + +@change the para of pwm + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device +> - para: the para of pwm + + + +```c +int hosal_pwm_freq_set(hosal_pwm_dev_t *pwm, uint32_t freq) +``` + +update PWM frequency + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device +> - freq: the PWM frequency (0~40M under limited duty) + + + +```c +int hosal_pwm_freq_get(hosal_pwm_dev_t *pwm, uint32_t *p_freq) +``` + +get PWM frequency + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device +> - p_freq: the pointer to memory frequency + + + +```c +int hosal_pwm_duty_set(hosal_pwm_dev_t *pwm, uint32_t duty) +``` + +set PWM duty + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device +> - duty: the PWM duty (original duty * 100) + + + +```c +int hosal_pwm_duty_get(hosal_pwm_dev_t *pwm, uint32_t *p_duty) +``` + +get PWM duty + +> `return` +> +> - success +> - other: fail +> +> `Parameters` +> +> - pwm: the PWM device +> - p_duty: the pointer to memory duty(original duty * 100) + + + +```c +int hosal_pwm_finalize(hosal_pwm_dev_t *pwm) +``` + +De-initialises an PWM interface, Turns off an PWM hardware interface. + +> > ``` +> > return +> > ``` +> +> - success +> - other: fail +> +> > ``` +> > Parameters +> > ``` +> +> - pwm: the PWM device +> - pwm: the interface which should be de-initialised + +#### Structures + +```c +struct hosal_pwm_config_t +``` + +pwm config struct + +> Public Members +> +> - `uint8_t pin` +> +> pwm pin +> +> - `uint32_t duty_cycle` +> +> the pwm duty_cycle 0 ~ 10000(0 ~ 100%) +> +> - `uint32_t freq` +> +> the pwm freq,range is between 0 and 40M + + + +```c +struct hosal_pwm_dev_t +``` + +pwm dev struct + +- `uint8_t port` + + pwm port + +- `hosal_pwm_config_t config` + + pwm config + +- `void *priv` + + priv data \ No newline at end of file diff --git a/docs/en-us/rng.md b/docs/en-us/rng.md new file mode 100644 index 000000000..9a9da7c09 --- /dev/null +++ b/docs/en-us/rng.md @@ -0,0 +1,46 @@ +# RNG API指南 + +------ + +## RNG API + +### 概述 + +随机数生成器(Random number generation),可以生成指定长度的随机数。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_rng.h + +#### Functions + +```c +int hosal_rng_init(void) +``` + +init rng + +> `return` +> +> - 0 : success +> - other: fail + + + +```c +int hosal_random_num_read(void *buf, uint32_t bytes) +``` + +Fill in a memory buffer with random data. + +> `return` +> +> - 0 : success +> - other: fail +> +> `Parameters` +> +> - buf: Point to a valid memory buffer, this function will fill in this memory with random numbers after executed +> - bytes: Length of the memory buffer (bytes) \ No newline at end of file diff --git a/docs/en-us/rtc.md b/docs/en-us/rtc.md new file mode 100644 index 000000000..b9d9f9349 --- /dev/null +++ b/docs/en-us/rtc.md @@ -0,0 +1,207 @@ +------ + +# RTC API指南 + +------ + +## RTC API + +## 概述 + +RTC(real-time clock)为操作系统中的实时时钟设备，为操作系统提供精准的实时时间和定时报警功能。当设备下电后，通过外置电池供电，RTC继续记录操作系统时间；设备上电后，RTC提供实时时钟给操作系统，确保断电后系统时间的连续性。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_rtc.h + +#### Functions + +```c +int hosal_rtc_init(hosal_rtc_dev_t *rtc) +``` + +This function will initialize the on board CPU real time clock. + +> `return` +> +> - 0 : success +> - other : fail +> +> `Parameters` +> +> - rtc: rtc device + + + +```c +int hosal_rtc_set_time(hosal_rtc_dev_t *rtc, const hosal_rtc_time_t *time) +``` + +This function will set MCU RTC time to a new value. + +> `return` +> +> - 0 : success +> - other : fail +> +> `Parameters` +> +> - rtc: rtc device +> - time: pointer to a time structure + + + +```c +int hosal_rtc_get_time(hosal_rtc_dev_t *rtc, hosal_rtc_time_t *time) +``` + +This function will return the value of time read from the on board CPU real time clock. + +> `return` +> +> - 0 : success +> - other : fail +> +> `Parameters` +> +> - rtc: rtc device +> - time: pointer to a time structure + + + +```c +int hosal_rtc_set_count(hosal_rtc_dev_t *rtc, uint64_t *time_stamp) +``` + +This function will set MCU RTC time to a new value. + +> `return` +> +> - 0 : success +> - other : fail +> +> `Parameters` +> +> - rtc: rtc device +> - time_stamp: new time value + + + +```c +int hosal_rtc_get_count(hosal_rtc_dev_t *rtc, uint64_t *time_stamp) +``` + +This function will return the value of time read from the on board CPU real time clock. + +> `return` +> +> - 0 : success +> - other : fail +> +> `Parameters` +> +> - rtc: rtc device +> - time_stamp: new time value + + + +```c +int hosal_rtc_finalize(hosal_rtc_dev_t *rtc) +``` + +De-initialises an RTC interface, Turns off an RTC hardware interface. + +> `return` +> +> - 0 : success +> - other : fail +> +> `Parameters` +> +> - RTC: the interface which should be de-initialised + + + +#### Structures + +```c +struct hosal_rtc_config_t +``` + +rtc config struct + +> Public Members +> +> - `uint8_t format` +> +> time formart DEC or BCD + +```c +struct hosal_rtc_dev_t +``` + +rtc dev struct + +> Public Members +> +> - `uint8_t port` +> +> rtc port +> +> - `hosal_rtc_config_t config` +> +> rtc config +> +> - `void *priv` +> +> priv data + +```c +struct hosal_rtc_time_t +``` + +- RTC time struct. + + Public Members + + ​ `uint8_t sec` + + ​ DEC format:value range from 0 to 59, BCD format:value range from 0x00 to 0x59 + + ​ `uint8_t min` + + ​ DEC format:value range from 0 to 59, BCD format:value range from 0x00 to 0x59 + + ​ `uint8_t hr` + + ​ DEC format:value range from 0 to 23, BCD format:value range from 0x00 to 0x23 + + ​ `uint8_t date` + + ​ DEC format:value range from 1 to 31, BCD format:value range from 0x01 to 0x31 + + `uint8_t month` + + ​ DEC format:value range from 1 to 12, BCD format:value range from 0x01 to 0x12 + + `uint16_t year` + + ​ DEC format:value range from 0 to 9999, BCD format:value range from 0x0000 to 0x9999 + + + +#### Macros + +```c +HOSAL_RTC_FORMAT_DEC +``` + +RTC DEC format + +```c +HOSAL_RTC_FORMAT_BCD +``` + +RTC BCD format \ No newline at end of file diff --git a/docs/en-us/spi.md b/docs/en-us/spi.md new file mode 100644 index 000000000..f5da3ff70 --- /dev/null +++ b/docs/en-us/spi.md @@ -0,0 +1,223 @@ +# SPI API指南 + +------ + +## SPI API + +### 概述 + +串行外设接口（Serial Peripheral Interface Bus, SPI）是一种用于短程通信的同步串行通信接口规范，装置之间使用全双工模式通信，是一个主机和一个或多个从机的主从模式。需要至 少4根线，事实上3根也可以（单向传输时）,包括SDI（数据输入）、SDO（数据输出）、SCLK（时钟）、CS（片选） + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_spi.h + +#### Functions + +```c +int hosal_spi_init(hosal_spi_dev_t *spi) +``` + +Initialises the SPI interface for a given SPI device. + +> `return` +> +> - 0 : on success +> - other : error +> +> `Parameters` +> +> - spi: the spi device + + + +```c +int hosal_spi_send(hosal_spi_dev_t *spi, const uint8_t *data, uint16_t size, uint32_t timeout) +``` + +Spi send. + +> `return` +> +> - 0 : on success +> - other : error +> +> `Parameters` +> +> - spi: the spi device +> - data: spi send data +> - size: spi send data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + +```c +int hosal_spi_recv(hosal_spi_dev_t *spi, uint8_t *data, uint16_t size, uint32_t timeout) +``` + +Spi recv. + +> `return` +> +> - 0 : success +> - other : error +> +> `Parameters` +> +> - spi: the spi device +> - data: spi recv data +> - size: spi recv data size +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + +```c +int hosal_spi_send_recv(hosal_spi_dev_t *spi, uint8_t *tx_data, uint8_t *rx_data, uint16_t size, uint32_t timeout) +``` + +spi send data and recv + +> `return` +> +> - 0 : success +> - other : error +> +> `Parameters` +> +> - spi: the spi device +> - tx_data: spi send data +> - rx_data: spi recv data +> - size: spi data to be sent and recived +> - timeout: timeout in milisecond, set this value to HAL_WAIT_FOREVER if you want to wait forever + + + +```c +int hosal_spi_irq_callback_set(hosal_spi_dev_t *spi, hosal_spi_irq_t pfn, void *p_arg) +int hosal_spi_set_cs(uint8_t pin, uint8_t value) +``` + +spi software set cs pin high/low only for master device + +> `return` +> +> - 0 : success +> - other : error +> +> `Parameters` +> +> - pin: cs pin +> - value: 0 or 1 + + + +```c +int hosal_spi_finalize(hosal_spi_dev_t *spi) +``` + +De-initialises a SPI interface. + +> `return` +> +> - 0 : success +> - other : error +> +> `Parameters` +> +> - spi: the SPI device to be de-initialised + + + +#### Structures + +```c +struct hosal_spi_config_t +``` + +Define spi config args. + +> Public Members +> +> - `uint8_t mode` +> +> spi communication mode +> +> - `uint8_t dma_enable` +> +> enable dma tansmission or not +> +> - `uint8_t polar_phase` +> +> spi polar and phase +> +> - `uint32_t freq` +> +> communication frequency Hz +> +> - `uint8_t pin_clk` +> +> spi clk pin +> +> - `uint8_t pin_mosi` +> +> spi mosi pin +> +> - `uint8_t pin_miso` +> +> spi miso pin + +```c +struct hosal_spi_dev_t +``` + +Define spi dev handle. + +> Public Members +> +> - `uint8_t port` +> +> spi port +> +> - `hosal_spi_config_t config` +> +> spi config +> +> - `hosal_spi_irq_t cb` +> +> spi interrupt callback +> +> - `void *p_arg` +> +> arg pass to callback +> +> - `void *priv` +> +> priv data + +#### Macros + +```c +HOSAL_SPI_MODE_MASTER +``` + +spi communication is master mode + +```c +HOSAL_SPI_MODE_SLAVE +``` + +spi communication is slave mode + +```c +HOSAL_WAIT_FOREVER +``` + +Define the wait forever timeout macro. + + + +#### Type Definitions + +```c +typedef void (*hosal_spi_irq_t)(void *parg) +``` + +spi irq callback function \ No newline at end of file diff --git a/docs/en-us/timer.md b/docs/en-us/timer.md new file mode 100644 index 000000000..9f341f7f2 --- /dev/null +++ b/docs/en-us/timer.md @@ -0,0 +1,152 @@ +# TIMER API指南 + +## 概述 + +通用定时器，用于定时，当时间到达我们所设置的定时时间会产生定时中断，可以用来完成定时任务。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_timer.h + +#### Functions + +```c +int hosal_timer_init(hosal_timer_dev_t *tim) +``` + +init a hardware timer + +`return` + +- 0 : on success +- other :error + +`Parameters` + +- tim: timer device + + + +```c +int hosal_timer_start(hosal_timer_dev_t *tim) +``` + +start a hardware timer + +`return` + +- 0 : on success +- other : error + +`Parameters` + +- tim: timer device + + + +```c +void hosal_timer_stop(hosal_timer_dev_t *tim) +``` + +stop a hardware timer + +`return` + +- none + +`Parameters` + +- tim: timer device + + + +```c +int hosal_timer_finalize(hosal_timer_dev_t *tim) +``` + +De-initialises an TIMER interface, Turns off an TIMER hardware interface + +`return` + +- 0 : success +- other : error + +`Parameters` + +- tim: timer device + +#### Structures + +```c +struct hosal_timer_config_t +``` + +Define timer config args + +> Public Members +> +> - `uint32_t period` +> +> timer period, us +> +> - `uint8_t reload_mode` +> +> auto reload or not +> +> - `hosal_timer_cb_t cb` +> +> timer handle when expired +> +> - `void *arg` +> +> timer handle args + + + +```c +struct hosal_timer_dev_t +``` + +Define timer dev handle + +> Public Members +> +> - `int8_t port` +> +> timer port +> +> - `hosal_timer_config_t config` +> +> timer config +> +> - `void *priv` +> +> priv data + + + +#### Macros + +```c +TIMER_RELOAD_PERIODIC +``` + +timer reload automatic + +```c +TIMER_RELOAD_ONCE +``` + +timer reload once and need to reload manually + + + +#### Type Definitions + +```c +typedef void (*hosal_timer_cb_t)(void *arg) +``` + +Define timer handle function type \ No newline at end of file diff --git a/docs/en-us/uart.md b/docs/en-us/uart.md new file mode 100644 index 000000000..ed09d44b4 --- /dev/null +++ b/docs/en-us/uart.md @@ -0,0 +1,579 @@ +# UART API指南 + +## 概述 + +通用异步收发传输器（Universal Asynchronous Receiver/Transmitter，通常称为UART）是一种异步收发传输器，提供了与外部设备进行全双工数据交换的灵活方式。 BL602共有2组UART口（UART0和UART1），通过配合DMA使用，可以实现高效的数据通信。 + + + +> 需要注意的是gpio的pin脚作为uart功能使用时，选取的gpio pin脚对8取余不能相等，如gpio0和gpio8不能同时做为uart的引脚。 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_uart.h + +#### Functions + +```c +int hosal_uart_abr_get(hosal_uart_dev_t *uart, uint8_t mode) +``` + +Get auto baudrate on a UART interface. + +> > return +> +> - 0 : on success +> - EIO if an error occurred with any step +> +> > Parameters +> +> - uart: the UART interface +> - mode: auto baudrate detection mode(codeword 0x55 or start bit) + + + +```c +int hosal_uart_init(hosal_uart_dev_t *uart) +``` + +Initialises a UART interface. + +> > return +> +> - 0 : on success +> - EIO if an error occurred with any step +> +> > Parameters +> +> - uart: the interface which should be initialised + + + +```c +int hosal_uart_send(hosal_uart_dev_t *uart, const void *txbuf, uint32_t size) +``` + +Poll transmit data on a UART interface. + +> > return +> +> - 0 : success +> - EIO if an error occurred with any step +> +> > Parameters +> +> - uart: the UART interface +> - txbuf: pointer to the start of data +> - size: number of bytes to transmit + + + +```c +int hosal_uart_receive(hosal_uart_dev_t *uart, void *data, uint32_t expect_size) +``` + +Poll receive data on a UART interface. + +> > return +> +> - 0 number of bytes to receive +> - EIO if an error occurred with any step +> +> > Parameters +> +> - uart: the UART interface +> - rxbuf: pointer to the buffer which will store incoming data +> - expect_size: expect number of bytes to receive + + + +```c +int hosal_uart_ioctl(hosal_uart_dev_t *uart, int ctl, void *p_arg) +``` + +hal uart ioctl + +> > return +> +> - 0 on success +> - EIO if an error occurred with any step +> +> > Parameters +> +> - uart: the UART interface +> - ctl: Control request +> - HOSAL_UART_BAUD_SET : baud set, p_arg is baud +> - HOSAL_UART_BAUD_GET : baud get, p_arg is baud’s pointer +> - HOSAL_UART_DATA_WIDTH_SET : set data width，p_arg is hosal_uart_data_width_t +> - HOSAL_UART_DATA_WIDTH_GET : get data width，p_arg is hosal_uart_data_width_t’s pointer +> - HOSAL_UART_STOP_BITS_SET : set stop bits, p_arg is hosal_uart_stop_bits_t +> - HOSAL_UART_STOP_BITS_GET : get stop bits, p_arg is hosal_uart_stop_bits_t’s pointer +> - HOSAL_UART_PARITY_SET : set parity, p_arg is hosal_uart_parity_t +> - HOSAL_UART_PARITY_GET : get parity, p_arg is hosal_uart_parity_t’s pointer +> - HOSAL_UART_MODE_SET : UART mode set, p_arg is hosal_uart_mode_t +> - HOSAL_UART_MODE_GET : UART mode get, p_arg is hosal_uart_mode_t’s pointer +> - HOSAL_UART_FLOWMODE_SET : UART flow mode set, p_arg is hosal_uart_flow_control_t +> - HOSAL_UART_FLOWSTAT_GET : UART flow state get, p_arg is hosal_uart_flow_control_t’s pointer +> - HOSAL_UART_FREE_TXFIFO_GET : get uart free tx fifo size (bytes) +> - HOSAL_UART_FREE_RXFIFO_GET : get uart free rx fifo size (bytes) +> - HOSAL_UART_FLUSH : Wait for the send to complete +> - HOSAL_UART_TX_TRIGGER_ON : UART TX trigger on +> - HOSAL_UART_TX_TRIGGER_OFF : UART TX trigger off +> - HOSAL_UART_DMA_CONFIG : p_arg is hosal_uart_dma_cfg_t’s pointer +> - HOSAL_UART_DMA_TX_START : UART DMA TX start trans p_arg is hosal_uart_dma_cfg_t’s pointer +> - HOSAL_UART_DMA_RX_START : UART DMA RX start trans p_arg is hosal_uart_dma_cfg_t’s pointer +> - p_arg: parameter + +```c +int hosal_uart_callback_set(hosal_uart_dev_t *uart, int callback_type, hosal_uart_callback_t pfn_callback, void *arg) +``` + +hal uart callback set + +> > return +> +> - 0 on success +> - EIO if an error occurred with any step +> +> > Parameters +> +> - uart: the UART interface +> +> - callback_type: callback type +> +> > - HOSAL_UART_TX_CALLBACK +> > - HOSAL_UART_RX_CALLBACK +> > - HOSAL_UART_TX_DMA_CALLBACK +> > - HOSAL_UART_RX_DMA_CALLBACK +> +> - pfn_callback: callback function +> +> - arg: callback function parameter + + + +```c +int hosal_uart_finalize(hosal_uart_dev_t *uart) +``` + +Deinitialises a UART interface. + +> `return` +> +> - 0 on success +> +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - uart: the interface which should be deinitialised + + + +#### Structures + +```c +struct hosal_uart_dma_cfg_t +``` + +UART DMA configuration. + +> Public Members +> +> - `uint8_t *dma_buf` +> +> UART DMA trans buffer When the transmission is TX, the address is the src address When the transmission is RX, the address is the dest address. +> +> - `uint32_t dma_buf_size` +> +> UART DMA trans buffer size. + +```c +struct hosal_uart_config_t +``` + +UART configuration. + +> Public Members +> +> - `uint8_t uart_id` +> +> UART id. +> +> - `uint8_t tx_pin` +> +> UART tx pin. +> +> - `uint8_t rx_pin` +> +> UART rx pin. +> +> - `uint8_t cts_pin` +> +> UART cts pin. +> +> - `uint8_t rts_pin` +> +> UART rts pin. +> +> - `uint32_t baud_rate` +> +> UART baud rate. +> +> - `hosal_uart_data_width_t data_width` +> +> UART data width. +> +> - `hosal_uart_parity_t parity` +> +> UART parity bit. +> +> - `hosal_uart_stop_bits_t stop_bits` +> +> UART stop btis. +> +> - `hosal_uart_flow_control_t flow_control` +> +> UART flow control. +> +> - `hosal_uart_mode_t mode` +> +> UART int or pull mode. + +```c +struct hosal_uart_dev_t +``` + +UART device type. + +> Public Members +> +> - `uint8_t port` +> +> UART port. +> +> - `hosal_uart_config_t config` +> +> UART config. +> +> - `hosal_uart_callback_t tx_cb` +> +> UART tx callback. +> +> - `void *p_txarg` +> +> UART tx callback arg. +> +> - `hosal_uart_callback_t rx_cb` +> +> UART rx callback. +> +> - `void *p_rxarg` +> +> UART rx callback arg. +> +> - `void *p_txdma_arg` +> +> UART tx dma callback. +> +> - `hosal_uart_callback_t rxdma_cb` +> +> UART rx dma callback. +> +> - `void *p_rxdma_arg` +> +> UART rx dma callback arg. +> +> - `hosal_dma_chan_t dma_tx_chan` +> +> UART dma rx channel. +> +> - `hosal_uart_callback_t rx_cb` +> +> UART rx callback. +> +> - `void *priv` +> +> UART private data. + +#### Macros + +```c +HOSAL_UART_AUTOBAUD_0X55 +``` + +UART auto baudrate detection using codeword 0x55. + +```c +HOSAL_UART_AUTOBAUD_STARTBIT +``` + +UART auto baudrate detection using start bit. + +```c +HOSAL_UART_TX_CALLBACK +``` + +UART tx idle interrupt callback. + +```c +HOSAL_UART_RX_CALLBACK +``` + +UART rx complete callback. + +```c +HOSAL_UART_TX_DMA_CALLBACK +``` + +UART tx DMA trans complete callback. + +```c +HOSAL_UART_RX_DMA_CALLBACK +``` + +UART rx DMA trans complete callback. + +```c +HOSAL_UART_BAUD_SET +``` + +UART baud set. + +```c +HOSAL_UART_BAUD_GET +``` + +UART baud get. + +```c +HOSAL_UART_DATA_WIDTH_SET +``` + +UART data width set. + +```c +HOSAL_UART_DATA_WIDTH_GET +``` + +UART data width get. + +```c +HOSAL_UART_STOP_BITS_SET +``` + +UART stop bits set. + +```c +HOSAL_UART_STOP_BITS_GET +``` + +UART stop bits get. + +```c +HOSAL_UART_FLOWMODE_SET +``` + +UART flow mode set. + +```c +HOSAL_UART_FLOWSTAT_GET +``` + +UART flow state get. + +```c +HOSAL_UART_PARITY_SET +``` + +UART flow mode set. + +```c +HOSAL_UART_PARITY_GET +``` + +UART flow state get. + +```c +HOSAL_UART_MODE_SET +``` + +UART mode set. + +```c +HOSAL_UART_MODE_GET +``` + +UART mode get. + +```c +HOSAL_UART_FREE_TXFIFO_GET +``` + +UART free tx fifo get. + +```c +HOSAL_UART_FREE_RXFIFO_GET +``` + +UART free rx fifo get. + +```c +HOSAL_UART_FLUSH +``` + +Wait for the send to complete. + +```c +HOSAL_UART_TX_TRIGGER_ON +``` + +UART TX trigger on. + +```c +HOSAL_UART_TX_TRIGGER_OFF +``` + +UART TX trigger off. + +```c +HOSAL_UART_DMA_TX_START +``` + +UART DMA TX start trans. + +```c +HOSAL_UART_DMA_RX_START +``` + +UART DMA RX start trans. + +```c +HOSAL_UART_CFG_DECL(cfg, id, tx, rx, baud) +``` + +define a UART default config + +> `Parameters` +> +> - cfg: config define +> - id: uart id +> - tx: uart tx pin +> - rx: uart rx pin +> - baud: uart baud + +#### Type Definitions + +```c +typedef int (*hosal_uart_callback_t)(void *p_arg) +``` + +hosal uart callback + +> > `return` +> +> - 0 on success +> +> - EIO if an error occurred with any step +> +> `Parameters` +> +> - p_arg: Set the custom parameters specified when the callback function is set + +#### Enumerations + +```c +enum hosal_uart_data_width_t +``` + +UART data width. + +Values: + +> ```c +> HOSAL_DATA_WIDTH_5BIT +> +> HOSAL_DATA_WIDTH_6BIT +> +> HOSAL_DATA_WIDTH_7BIT +> +> HOSAL_DATA_WIDTH_8BIT +> +> HOSAL_DATA_WIDTH_9BIT +> +> ``` + +```c +enum hosal_uart_stop_bits_t +``` + +UART stop bits. + +Values: + +> ```c +> HOSAL_STOP_BITS_1 = 1 +> +> HOSAL_STOP_BITS_2 = 3 +> ``` + +```c +enum hosal_uart_flow_control_t +``` + +UART flow control. + +Values: + +> ```c +> HOSAL_FLOW_CONTROL_DISABLED +> +> HOSAL_FLOW_CONTROL_RTS +> +> HOSAL_FLOW_CONTROL_CTS +> +> HOSAL_FLOW_CONTROL_CTS_RTS +> +> ``` + +```c +enum hosal_uart_parity_t +``` + +UART parity. + +Values: + +> ```c +> HOSAL_NO_PARITY +> +> HOSAL_ODD_PARITY +> +> HOSAL_EVEN_PARITY +> ``` + +```c +enum hosal_uart_mode_t +``` + +UART mode. + +> Values: +> +> ​ `HOSAL_UART_MODE_POLL` +> +> - UART poll mode (default mode) +> +> `HOSAL_UART_MODE_INT_TX` +> +> - UART TX int mode. +> +> `HOSAL_UART_MODE_INT_RX` +> +> - UART RX int mode. +> +> `HOSAL_UART_MODE_INT` +> +> UART TX and RX int mode. \ No newline at end of file diff --git a/docs/en-us/wdg.md b/docs/en-us/wdg.md new file mode 100644 index 000000000..c9376db3d --- /dev/null +++ b/docs/en-us/wdg.md @@ -0,0 +1,87 @@ +# WDG API指南 + +## 概述 + +看门狗（Watchdog），又叫看门狗计时器（Watchdog timer），是一种硬件的计时设备，当系统的主程序发生某些错误时，导致未及时清除看门狗计时器的计时值，这时看门狗计时器就会对系统发出复位信号，使系统从悬停状态恢复到正常运作状态 + +### API参考 + +#### Header File + +- components/platform/hosal/include/hosal_wdg.h + +#### Functions + +```c +int hosal_wdg_init(hosal_wdg_dev_t *wdg) +``` + +This function will initialize the on board CPU hardware watch dog. + +`return` + +- 0 : success +- other: fail + +`Parameters` + +- wdg: the watch dog device + +```c +void hosal_wdg_reload(hosal_wdg_dev_t *wdg) +``` + +Reload watchdog counter. + +`Parameters` + +- wdg: the watch dog device + + + +```c +int hosal_wdg_finalize(hosal_wdg_dev_t *wdg) +``` + +This function performs any platform-specific cleanup needed for hardware watch dog. + +`return` + +- 0 : success +- other: fail + +`Parameters` + +- wdg: the watch dog device + +#### Structures + +```c +struct hosal_wdg_config_t +``` + +wdg config struct + +> > Public Members +> > +> > - `uint32_t timeout` +> > +> > Watchdag timeout in ms +> > +> > - `structhosal_wdg_dev_t` +> > +> > wdg dev struct +> +> Public Members +> +> > - `uint8_t port` +> > +> > wdg port +> > +> > - `hosal_wdg_config_t config` +> > +> > wdg config +> > +> > - `void *priv` +> > +> > priv data \ No newline at end of file diff --git a/docs/en-us/wifi.md b/docs/en-us/wifi.md new file mode 100644 index 000000000..905f46ea9 --- /dev/null +++ b/docs/en-us/wifi.md @@ -0,0 +1,505 @@ +# WiFi API指南 + +## API参考 + +### Header File + +- components/network/wifi_manager/bl60x_wifi_driver/include/wifi_mgmr_ext.h + +### Functions + +```c +int wifi_mgmr_psk_cal(char *password, char *ssid, int ssid_len, char *output) +``` + +```c +int wifi_mgmr_drv_init(wifi_conf_t *conf) +``` + +```c +int wifi_mgmr_init(void) +``` + +```c +void wifi_mgmr_start(void) +``` + +```c +void wifi_mgmr_start_background(wifi_conf_t *conf) +``` + +```c +void wifi_mgmr_get_wifi_channel_conf(wifi_conf_t *wifi_chan_conf) +``` + +```c +wifi_interface_t wifi_mgmr_sta_enable(void) +``` + +```c +int wifi_mgmr_sta_disable(wifi_interface_t *interface) +``` + +```c +struct netif *wifi_mgmr_sta_netif_get(void) +``` + +```c +struct netif *wifi_mgmr_ap_netif_get(void) +``` + +```c +int wifi_mgmr_sta_mac_set(uint8_t mac[6]) +``` + +```c +int wifi_mgmr_sta_mac_get(uint8_t mac[6]) +``` + +```c +int wifi_mgmr_sta_ip_get(uint32_t *ip, uint32_t *gw, uint32_t *mask) +``` + +```c +int wifi_mgmr_sta_ip_set(uint32_t ip, uint32_t mask, uint32_t gw, uint32_t dns1, uint32_t dns2) +``` + +```c +int wifi_mgmr_sta_dns_get(uint32_t *dns1, uint32_t *dns2) +``` + +```c +int wifi_mgmr_sta_ip_unset(void) +``` + +```c +int wifi_mgmr_sta_connect_ext(wifi_interface_t *wifi_interface, char *ssid, char *passphr, const ap_connect_adv_t *conn_adv_param) +``` + +```c +int wifi_mgmr_sta_connect_mid(wifi_interface_t *wifi_interface, char *ssid, char *psk, char *pmk, uint8_t *mac, uint8_t band, uint8_t chan_id, uint8_t use_dhcp, uint32_t flags) +``` + +```c +int wifi_mgmr_sta_connect(wifi_interface_t *wifi_interface, char *ssid, char *psk, char *pmk, uint8_t *mac, uint8_t band, uint8_t chan_id) +``` + +```c +int wifi_mgmr_sta_disconnect(void) +``` + +```c +int wifi_sta_ip4_addr_get(uint32_t *addr, uint32_t *mask, uint32_t *gw, uint32_t *dns) +``` + +```c +int wifi_mgmr_sta_ps_enter(uint32_t ps_level) +``` + +```c +int wifi_mgmr_sta_ps_exit() +``` + +```c +int wifi_mgmr_sta_autoconnect_enable(void) +``` + +```c +int wifi_mgmr_sta_autoconnect_disable(void) +``` + +```c +void wifi_mgmr_sta_ssid_set(char *ssid) +``` + +```c +void wifi_mgmr_sta_passphr_set(char *passphr) +``` + +```c +void wifi_mgmr_sta_psk_set(char *psk) +``` + +```c +void wifi_mgmr_sta_connect_ind_stat_get(wifi_mgmr_sta_connect_ind_stat_info_t *wifi_mgmr_ind_stat) +``` + +```c +wifi_interface_t wifi_mgmr_ap_enable(void) +``` + +```c +int wifi_mgmr_ap_mac_set(uint8_t mac[6]) +``` + +```c +int wifi_mgmr_ap_mac_get(uint8_t mac[6]) +``` + +```c +int wifi_mgmr_ap_ip_get(uint32_t *ip, uint32_t *gw, uint32_t *mask) +``` + +```c +int wifi_mgmr_ap_stop(wifi_interface_t *interface) +``` + +```c +int wifi_mgmr_ap_start(wifi_interface_t *interface, char *ssid, int hidden_ssid, char *passwd, int channel) +``` + +```c +int wifi_mgmr_ap_start_adv(wifi_interface_t *interface, char *ssid, int hidden_ssid, char *passwd, int channel, uint8_t use_dhcp) +``` + +```c +int wifi_mgmr_ap_start_atcmd(wifi_interface_t *interface, char *ssid, int hidden_ssid, char *passwd, int channel, int max_sta_supported) +``` + +```c +int wifi_mgmr_ap_sta_cnt_get(uint8_t *sta_cnt) +``` + +```c +int wifi_mgmr_ap_sta_info_get(struct wifi_sta_basic_info *sta_info, uint8_t idx) +``` + +```c +int wifi_mgmr_ap_sta_delete(uint8_t sta_idx) +``` + +```c +int wifi_mgmr_ap_set_gateway(char *gateway) +``` + +```c +int wifi_mgmr_sniffer_enable(void) +``` + +```c +int wifi_mgmr_sniffer_disable(void) +``` + +```c +int wifi_mgmr_rate_config(uint16_t config) +``` + +```c +int wifi_mgmr_conf_max_sta(uint8_t max_sta_supported) +``` + +```c +int wifi_mgmr_sniffer_register(void *env, sniffer_cb_t cb) +``` + +```c +int wifi_mgmr_sniffer_unregister(void *env) +``` + +```c +int wifi_mgmr_sniffer_register_adv(void *env, sniffer_cb_adv_t cb) +``` + +```c +int wifi_mgmr_sniffer_unregister_adv(void *env) +``` + +```c +int wifi_mgmr_state_get(int *state) +``` + +```c +int wifi_mgmr_detailed_state_get(int *state, int *state_detailed) +``` + +```c +int wifi_mgmr_status_code_get(int *s_code) +``` + +```c +int wifi_mgmr_rssi_get(int *rssi) +``` + +```c +int wifi_mgmr_channel_get(int *channel) +``` + +```c +int wifi_mgmr_channel_set(int channel, int use_40Mhz) +``` + +```c +int wifi_mgmr_all_ap_scan(wifi_mgmr_ap_item_t **ap_ary, uint32_t *num) +``` + +```c +int wifi_mgmr_scan_filter_hidden_ssid(int filter) +``` + +```c +int wifi_mgmr_scan(void *data, scan_complete_cb_t cb) +``` + +```c +int wifi_mgmr_scan_adv(void *data, scan_complete_cb_t cb, uint16_t *channels, uint16_t channel_num, const uint8_t bssid[6], const char *ssid, uint8_t scan_mode, uint32_t duration_scan) +``` + +```c +int wifi_mgmr_cfg_req(uint32_t ops, uint32_t task, uint32_t element, uint32_t type, uint32_t length, uint32_t *buf) +``` + +```c +int wifi_mgmr_scan_complete_callback() +``` + +```c +int wifi_mgmr_cli_scanlist(void) +``` + +```c +int wifi_mgmr_cli_init(void) +``` + +```c +int wifi_mgmr_scan_ap(char *ssid, wifi_mgmr_ap_item_t *item) +``` + +```c +int wifi_mgmr_scan_ap_all(wifi_mgmr_ap_item_t *env, uint32_t *param1, scan_item_cb_t cb) +``` + +```c +int wifi_mgmr_raw_80211_send(uint8_t *pkt, int len) +``` + +```c +int wifi_mgmr_set_country_code(char *country_code) +``` + +```c +int wifi_mgmr_ext_dump_needed() +``` + +```c +const char *wifi_mgmr_status_code_str(uint16_t status_code) +``` + +```c +int wifi_mgmr_beacon_interval_set(uint16_t beacon_int) +``` + +```c +void wifi_mgmr_conn_result_get(uint16_t *status_code, uint16_t *reason_code) +``` + +```c +int wifi_mgmr_set_wifi_active_time(uint32_t ms) +``` + +```c +int wifi_mgmr_set_listen_interval(uint16_t itv) +``` + +```c +int wifi_mgmr_pm_ops_register(void) +``` + +```c +int wifi_mgmr_fw_affair_ops(void) +``` + +```c +int wifi_mgmr_bcnind_auth_to_ext(int auth) +``` + +```c +int wifi_mgmr_bcnind_cipher_to_ext(int cipher) +``` + +```c +struct sm_connect_tlv_desc *wifi_mgmr_diagnose_tlv_get_ele(void) +``` + +```c +void wifi_mgmr_diagnose_tlv_free_ele(struct sm_connect_tlv_desc *ele) +``` + + + + + +### Structures + +```c + +struct ap_connect_adv + +struct bl_rx_info + +struct wifi_mgmr_ap_item + +struct wifi_mgmr_sta_connect_ind_stat_info + +struct wifi_sta_basic_info + +struct wifi_sta_ps_conf +``` + +Public Members + +```c +int listen_interval +``` + +num of beacons + +```c +uint16_t wifi_active_period +``` + +wifi active ms. + +```c +struct wifi_conf +``` + +### Macros + +```c +WIFI_CONNECT_STOP_SCAN_ALL_CHANNEL_IF_TARGET_AP_FOUND + +WIFI_CONNECT_PCI_EN + +WIFI_CONNECT_STOP_SCAN_CURRENT_CHANNEL_IF_TARGET_AP_FOUND + +WIFI_CONNECT_PMF_CAPABLE + +WIFI_CONNECT_PMF_REQUIRED + +WIFI_STATE_AP_IS_ENABLED(status) +``` + +### Type Definitions + +```c +typedef struct ap_connect_adv ap_connect_adv_t + +typedef struct bl_rx_info bl_rx_info_t + +typedef struct wifi_mgmr_ap_item wifi_mgmr_ap_item_t + +typedef struct wifi_mgmr_sta_connect_ind_stat_info wifi_mgmr_sta_connect_ind_stat_info_t + +typedef struct wifi_sta_basic_info wifi_sta_basic_info_t + +typedef struct wifi_sta_ps_conf wifi_sta_ps_conf_t + +typedef void *wifi_interface_t + +typedef void (*sniffer_cb_t)(void *env, uint8_t *pkt, int len, bl_rx_info_t *info) + +typedef void (*sniffer_cb_adv_t)(void *env, void *pkt_wrap, bl_rx_info_t *info) + +typedef void (*scan_item_cb_t)(wifi_mgmr_ap_item_t *env, uint32_t *param1, wifi_mgmr_ap_item_t *item) + +typedef void (*scan_complete_cb_t)(void *data, void *param) + +typedef struct wifi_conf wifi_conf_t +``` + +### Enumerations + +> ```c +> enum ap_info_type +> ``` +> +> **Values:** + +- AP_INFO_TYPE_SUGGEST +- AP_INFO_TYPE_PRESIST + +> ```c +> enum wifi_mgmr_ap_cipher_t +> ``` +> +> **Values:** + +- WM_WIFI_CIPHER_NONE=0 +- WM_WIFI_CIPHER_WEP +- WM_WIFI_CIPHER_AES +- WM_WIFI_CIPHER_TKIP +- WM_WIFI_CIPHER_TKIP_AES +- WM_WIFI_CIPHER_MAX + +> ```c +> enum wifi_mgmr_ap_auth_mode_t +> ``` +> +> **Values:** + +- WM_WIFI_AUTH_UNKNOWN = 0 +- WM_WIFI_AUTH_OPEN +- WM_WIFI_AUTH_WEP +- WM_WIFI_AUTH_WPA_PSK +- WM_WIFI_AUTH_WPA2_PSK +- WM_WIFI_AUTH_WPA_WPA2_PSK +- WM_WIFI_AUTH_WPA_ENTERPRISE +- WM_WIFI_AUTH_WPA3_SAE +- WM_WIFI_AUTH_WPA2_PSK_WPA3_SAE +- WM_WIFI_AUTH_MAX + +> ```c +> enum [anonymous] Power Save mode setting. +> ``` +> +> **Values:** + +- PS_MODE_OFF Power-save off. +- PS_MODE_ON Power-save on - Normal mode. +- PS_MODE_ON_DYN Power-save on - Dynamic mode. + +> ```c +> enum WIFI_STATE_ENUM_LIST +> ``` +> +> **Values:** + +- WIFI_STATE_UNKNOWN = 0x00 +- WIFI_STATE_IDLE = 0x01 +- WIFI_STATE_CONNECTING = 0x02 +- WIFI_STATE_CONNECTED_IP_GETTING = 0x03 +- WIFI_STATE_CONNECTED_IP_GOT = 0x04 +- WIFI_STATE_DISCONNECT = 0x05 +- WIFI_STATE_WITH_AP_IDLE = 0x11 +- WIFI_STATE_WITH_AP_CONNECTING = 0x12 +- WIFI_STATE_WITH_AP_CONNECTED_IP_GETTING = 0x13 +- WIFI_STATE_WITH_AP_CONNECTED_IP_GOT = 0x14 +- WIFI_STATE_WITH_AP_DISCONNECT = 0x15 +- WIFI_STATE_IFDOWN = 0x06 +- WIFI_STATE_SNIFFER = 0x07 +- WIFI_STATE_PSK_ERROR = 0x08 +- WIFI_STATE_NO_AP_FOUND = 0x09 + +> ```c +> enum WIFI_SCAN_DONE_EVENT_TYPE +> ``` +> +> **Values:** + +- WIFI_SCAN_DONE_EVENT_OK = 0x00 +- WIFI_SCAN_DONE_EVENT_BUSY = 0x01 + +> ```c +> enum WIFI_COEX_PM_LEVEL +> ``` +> +> **Values:** + +- WIFI_COEX_PM_STA_NONE = PM_MODE_STA_NONE +- WIFI_COEX_PM_STA_IDLE = PM_MODE_STA_IDLE +- WIFI_COEX_PM_STA_MESH = PM_MODE_STA_MESH +- WIFI_COEX_PM_STA_DOZE = PM_MODE_STA_DOZE +- WIFI_COEX_PM_STA_COEX = PM_MODE_STA_COEX +- WIFI_COEX_PM_STA_DOWN = PM_MODE_STA_DOWN +- WIFI_COEX_PM_AP_IDLE = PM_MODE_AP_IDLE +- WIFI_COEX_PM_MAX = PM_MODE_MA \ No newline at end of file diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 000000000..4e1670aa3 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,46 @@ + + + + + Document + + + + + + +
Please wait...
+ + + + + + + + + + + + + diff --git a/docs/zh-cn/.nojekyll b/docs/zh-cn/.nojekyll new file mode 100644 index 000000000..e69de29bb diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 000000000..3971bef0d --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,3 @@ +# 头部 + +> 一点说明. diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md new file mode 100644 index 000000000..2bfcc8a89 --- /dev/null +++ b/docs/zh-cn/_sidebar.md @@ -0,0 +1,5 @@ +* 快速开始 + * [家目录](/zh-cn/README.md) +* 参考手册 + * [花园](/zh-cn/guide.md "The greatest guide in the world") +* API diff --git a/docs/zh-cn/guide.md b/docs/zh-cn/guide.md new file mode 100644 index 000000000..f8b5bb6be --- /dev/null +++ b/docs/zh-cn/guide.md @@ -0,0 +1,4 @@ +# 你好 +--- + +> 只有测试 2025-02-15 19:31 From 8058e302dd1795dc5814891fc3b1d59d2012f3d2 Mon Sep 17 00:00:00 2001 From: WildboarG <959586@outlook.com> Date: Wed, 19 Feb 2025 11:30:23 +0800 Subject: [PATCH 02/17] Add a description of the document --- README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 71 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c45377e71..bf9199f8d 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,16 @@ Ai-Thinker Ai-WB2 Wireless Modules Development Framework ========= + + Base on th Bouffalolab bl_iot_sdk. Support BL602 Wi-Fi/BLE Combo RISC-V based Chip and BL70X Zigbee/BLE RISC-V based Chip. + + # Linux Users + + ## Step 1. Install Prerequisites In order to use Ai-WB2 Development Framework with the Ai-WB2, you need to install some software packages based on your Operating System. This setup guide will help you on getting everything installed on Linux and macOS based systems. @@ -15,7 +21,7 @@ In order to use Ai-WB2 Development Framework with the Ai-WB2, you need to instal - One liner for Arch: -`sudo pacman -S base-devel python python-pip git screen` +`paru -S aithinkerwb2 ` or `yay -S aithinkerwb2` - Next, clone the SDK repository: @@ -25,6 +31,8 @@ if you are coding in the China , recommend you to clone the repository : `git clone --recursive https://gitee.com/Ai-Thinker-Open/Ai-Thinker-WB2` + + ## Step 2. Modify Permission Modify the permissions of the compilation tool chain to enable executable functions. - Darwin @@ -42,25 +50,32 @@ Modify the permissions of the compilation tool chain to enable executable functi cd toolchain/riscv/MSYS/ . chmod755.sh ``` + + ## Step 3. Compiling For example, run the cd applications/get-started/helloworld project to compile : -``` +```bash cd applications/get-started/helloworld make -j8 ``` + + ## Step 4. download Please connect your Ai-WB2 Serial Development board , and press the EN button according to the prompts. -``` +```bash make flash p=/dev/ttyUSB0 b=921600 ``` + + ## Step 5. Other + In addition, you can use this command to view help. -``` +```bash make help ``` > Your configuration chipname is Ai-Thinker Ai-WB2 Wi-Fi&BLE Module @@ -78,6 +93,57 @@ make help Note: After erasing the flash, you need to use this command to download it,but always press the BURN button,then press the EN button.next,release all keys. -``` +```bash make eflash ``` + + + + + +# API Guide + +--- + +Read the documentation located in the `docs` directory under `en-us`. + +To visualize and load a document locally, you can start an HTTP server in the `docs` directory. Here’s how you can do it: + +1. **Using Python** (if you have Python installed): + + - Navigate to the docs directory: + + ```bash + cd /path/to/docs + ``` + + - Start a simple HTTP server + + - for Python3.x: + + ```bash + python3 -m http.server 8000 + ``` + + - for Python2.x: + + ```bash + python -m SimpleHTTPServer 8000 + ``` + +2. **Using Node.js**: If you prefer using Node.js, you can use a package like `http-server`: + + - Install `http-server` globally: + + ```bash + npm install -g http-server + ``` + + - Navigate to the `docs` directory and run the server: + + ```bash + cd /path/to/docs + http-server -p 8000 + ``` + + Once the server is running, you can access the documents in your browser by going to `http://localhost:8000`. From 6c9b01a854e4274763e95822523077a6076c2b5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=9D=8F=E7=8B=97?= <959586@outlook.com> Date: Wed, 19 Feb 2025 13:06:18 +0800 Subject: [PATCH 03/17] Update index.html --- docs/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.html b/docs/index.html index 4e1670aa3..eb78dcc96 100644 --- a/docs/index.html +++ b/docs/index.html @@ -13,7 +13,7 @@