.. _User-AT:

用户 AT 命令
=================

:link_to_translation:`en:[English]`

-  :ref:`AT+USERRAM <cmd-USERRAM>`：操作用户的空闲 RAM
-  :ref:`AT+USEROTA <cmd-USEROTA>`：根据指定 URL 升级固件
-  :ref:`AT+USERWKMCUCFG <cmd-USERWKMCUCFG>`：设置 AT 唤醒 MCU 的配置
-  :ref:`AT+USERMCUSLEEP <cmd-USERMCUSLEEP>`：MCU 指示自己睡眠状态

.. _cmd-USERRAM:

:ref:`AT+USERRAM <User-AT>`: 操作用户的空闲 RAM
----------------------------------------------------------
查询命令
^^^^^^^^

**功能：**

查询用户当前可用的 RAM 大小

**命令：**

::

    AT+USERRAM?

**响应：**

::

    +USERRAM:<size>

    OK

设置命令
^^^^^^^^

**功能：**

分配、读、写、擦除、释放用户 RAM 空间

**命令：**

::

    AT+USERRAM=<operation>,<size>[,<offset>]

**响应：**

::

    +USERRAM:<length>,<data>    // 只有是读操作时，才会有这个回复

    OK

参数
^^^^

-  **<operation>**：

   -  0：释放用户 RAM 空间
   -  1：分配用户 RAM 空间
   -  2：向用户 RAM 写数据
   -  3：从用户 RAM 读数据
   -  4：清除用户 RAM 上的数据

-  **<size>**: 分配/读/写的用户 RAM 大小
-  **<offset>**: 读/写 RAM 的偏移量。默认值：0

说明
^^^^

- 请在执行任何其他操作之前分配用户 RAM 空间。
- 当 ``<operator>`` 为 ``write`` 时，系统收到此命令后先换行返回 ``>``，此时您可以输入要写的数据，数据长度应与 ``<length>`` 一致。
- 当 ``<operator>`` 为 ``read`` 时并且长度大于 1024，ESP-AT 会以同样格式多次回复，每次回复最多携带 1024 字节数据，最终以 ``\r\nOK\r\n`` 结束。

示例
^^^^

::

    // 分配 1 KB 用户 RAM 空间
    AT+USERRAM=1,1024

    // 向 RAM 空间开始位置写入 500 字节数据
    AT+USERRAM=2,500

    // 从 RAM 空间偏移 100 位置读取 64 字节数据
    AT+USERRAM=3,64,100

    // 释放用户 RAM 空间
    AT+USERRAM=0

.. _cmd-USEROTA:

:ref:`AT+USEROTA <User-AT>`：根据指定 URL 升级固件
---------------------------------------------------------------------

ESP-AT 在运行时，通过从指定 URL 下载新固件进行升级。

设置命令
^^^^^^^^

**功能：**

升级到 URL 指定版本的固件

**命令：**

::

    AT+USEROTA=<url len>

**响应：**

::

    OK

    >

上述响应表示 AT 已准备好接收 URL，此时您可以输入 URL，当 AT 接收到的 URL 长度达到 ``<url len>`` 后，返回：

::

    Recv <url len> bytes

AT 输出上述信息之后，升级过程开始。如果升级完成，返回：

::

    OK

如果参数错误或者固件升级失败，返回：

::

    ERROR

参数
^^^^

-  **<url len>**：URL 长度。最大值：8192 字节

说明
^^^^

-  您可以 `从 GitHub Actions 里下载 <https://docs.espressif.com/projects/esp-at/zh_CN/latest/esp32/Compile_and_Develop/How_to_download_the_latest_temporary_version_of_AT_from_github.html>`_ 所需要的 OTA 固件，也可以自行 :doc:`编译 ESP-AT 工程 <../Compile_and_Develop/How_to_clone_project_and_compile_it>` 生成所需要的 OTA 固件。
-  OTA 固件为 ``build/esp-at.bin``。
-  升级速度取决于网络状况。
-  如果网络条件不佳导致升级失败，AT 将返回 ``ERROR``，请等待一段时间再试。
-  不建议降级到旧版本。降到旧版本可能会出现兼容性问题和无法运行的风险。如果您坚持要降级到旧版本，请根据您的产品自行测试验证功能。
-  建议升级 AT 固件后，调用 :ref:`AT+RESTORE <cmd-RESTORE>` 恢复出厂设置。
-  ``AT+USEROTA`` 仅支持 ``HTTP``。
-  AT 输出 ``>`` 字符后，数据中的特殊字符不需要转义字符进行转义，也不需要以新行结尾 (CR-LF)。
-  请参考 :doc:`../Compile_and_Develop/How_to_implement_OTA_update` 获取更多 OTA 命令。

示例
^^^^

::

    AT+USEROTA=36

    OK

    >
    Recv 36 bytes

    OK

.. _cmd-USERWKMCUCFG:

:ref:`AT+USERWKMCUCFG <User-AT>`：设置 AT 唤醒 MCU 的配置
---------------------------------------------------------------------

设置命令
^^^^^^^^

**功能：**

此命令配置 AT 如何检查 MCU 的唤醒状态，以及 AT 如何唤醒 MCU。

- 当 MCU 是醒来的状态，AT 将直接向 MCU 发送数据，不会发送唤醒信号。
- 当 MCU 是睡眠的状态，AT 准备向 MCU 主动发送数据时（主动发送的数据和 `ESP-AT 消息报告 <https://docs.espressif.com/projects/esp-at/zh-cn/release-v2.2.0.0_esp8266/AT_Command_Set/index.html#id5>`_ 中定义的相同），AT 会先发送唤醒信号再发送数据。MCU 被唤醒或者超时后会清除唤醒信号。

**命令：**

::

    AT+USERWKMCUCFG=<enable>,<wake mode>,<wake number>,<wake signal>,<delay time>[,<check mcu awake method>]

**响应：**

::

    OK

参数
^^^^

- **<enable>**：启用或禁用唤醒配置。

  - 0：禁用唤醒 MCU 配置
  - 1：使能唤醒 MCU 配置

- **<wake mode>**：唤醒模式。

  - 1：GPIO 唤醒
  - 2：UART 唤醒

- **<wake number>**：该参数的意义取决于 ``<wake mode>`` 的值。

  - 如果 ``<wake mode>`` 是 1，``<wake number>`` 代表唤醒管脚 GPIO 编号。用户需要保证配置的唤醒管脚没有用作其它用途，否则需要用户做兼容性处理。
  - 如果 ``<wake mode>`` 是 2，``<wake number>`` 代表唤醒 UART 编号。当前只支持 1，即支持 UART1 唤醒 MCU。

- **<wake signal>**：该参数的意义取决于 ``<wake mode>`` 的值。

  - 如果 ``<wake mode>`` 是 1，``<wake signal>`` 代表唤醒电平。

    - 0：低电平
    - 1：高电平

  - 如果 ``<wake mode>`` 是 2，``<wake signal>`` 代表唤醒字节。范围：[0,255]。

- **<delay time>**：最长等待时间。单位：毫秒。范围：[0,60000]。该参数的意义取决于 ``<wake mode>`` 的值。

  - 如果 ``<wake mode>`` 是 1，则在 ``<delay time>`` 期间内，将一直保持 ``<wake signal>`` 电平。``<delay time>`` 到后，则反转 ``<wake signal>`` 电平。
  - 如果 ``<wake mode>`` 是 2，则立即发送 ``<wake signal>`` 字节，进入等待直到超时。

- **<check mcu awake method>**：AT 检查 MCU 是否处于醒来的状态。

  - Bit 0：是否开启与 :ref:`AT+USERMCUSLEEP <cmd-USERMCUSLEEP>` 命令的关联。默认开启。即：收到 AT+USERMCUSLEEP=0 命令，指示 MCU 醒来；收到 AT+USERMCUSLEEP=1 命令，指示 MCU 睡眠。
  - Bit 1：是否开启与 :ref:`AT+SLEEP=0/1/2/3 <cmd-SLEEP>` 命令的关联。默认禁用。即：收到 AT+SLEEP=0 命令，指示 MCU 醒来；收到 AT+SLEEP=1/2/3 命令，指示 MCU 睡眠。
  - Bit 2：是否开启 ``<delay time>`` 超时后指示 MCU 醒来功能。默认禁用。即：禁用时，delay time 后，指示 MCU 睡眠；使能时，delay time 后，指示 MCU 醒来。
  - Bit 3（暂未实现）：是否开启 GPIO 指示 MCU 醒来功能。默认不支持。

说明
^^^^

- 此命令只需要配置一次。
- 每次 AT 向 MCU 主动发送数据前，会先发送唤醒信号再进入等待，``<delay time>`` 时间到了之后直接发送数据。此超时会降低与 MCU 间的传输效率。
- 如果在 ``<delay time>`` 毫秒之前，AT 收到 ``<check mcu awake method>`` 里的任意唤醒事件，则立即清除唤醒状态；否则会等待 ``<delay time>`` 超时后，会自动清除唤醒状态。

示例
^^^^

::

    // 使能唤醒 MCU 配置。每次 AT 向 MCU 发送数据前，会先使用 Wi-Fi 模块的 GPIO18 管脚，高电平唤醒 MCU，同时保持高电平 10 秒。
    AT+USERWKMCUCFG=1,1,18,1,10000,3

    // 禁用唤醒 MCU 配置
    AT+USERWKMCUCFG=0

.. _cmd-USERMCUSLEEP:

:ref:`AT+USERMCUSLEEP <User-AT>`：MCU 指示自己睡眠状态
-----------------------------------------------------------

设置命令
^^^^^^^^

**功能：**

在 :ref:`AT+USERWKMCUCFG <cmd-USERWKMCUCFG>` 命令的 ``<check mcu awake method>`` Bit 0 配置情况下，此命令才会生效。用于告知 AT 当前 MCU 的睡眠状态。

**命令：**

::

    AT+USERMCUSLEEP=<state>

**响应：**

::

    OK

参数
^^^^

- **<state>**：

  - 0：指示 MCU 醒来。
  - 1：指示 MCU 睡眠。

示例
^^^^

::

    // MCU 告知 AT 当前 MCU 醒来
    AT+USERMCUSLEEP=0