Skip to content

yuanxiaoming8899/thingspeak-arduino

BranchesTags
 
 

Repository files navigation

适用于 Arduino、ESP8266 和 ESP32 的 ThingSpeak 通信库

该库使 Arduino 或其他兼容硬件能够向 ThingSpeak 写入数据或从 ThingSpeak 读取数据，ThingSpeak 是一个具有 MATLAB 分析和可视化功能的物联网开放数据平台。

此处提供了硬件特定示例。但为了让您了解使用 ESP8266 进行写入和读取的使用示例，如下所示。完整文档也如下所示。

ThingSpeak 提供免费的数据存储和带时间戳的数字或字母数字数据分析。用户可以通过访问http://thingspeak.com并创建 ThingSpeak 用户帐户来访问 ThingSpeak。

ThingSpeak 将数据存储在通道中。通道支持无限数量的带时间戳的观察值（可将其视为电子表格中的行）。每个通道最多有 8 个字段（可将其视为电子表格中的列）。观看此视频了解概述。

频道可以是公共的，任何人都可以看到数据，也可以是私有的，只有所有者和选定用户可以读取数据。每个频道都有一个关联的写入 API 密钥，用于控制谁可以写入频道。此外，私有频道有一个或多个读取 API 密钥来控制谁可以从私有频道读取。从公共频道读取不需要 API 密钥。每个频道最多可以有 8 个字段。默认情况下会创建一个字段。

您可以使用内置版本的 MATLAB 在 ThingSpeak 上可视化数据并进行在线分析，或者使用桌面版本的 MATLAB 获取更深入的历史洞察。请访问https://www.mathworks.com/hardware-support/thingspeak.html了解更多信息。

粒子设备的库和示例可以在这里找到：https://github.com/mathworks/thingspeak-particle

安装

在 Arduino IDE 中，选择 Sketch/Include Library/Manage Libraries。从列表中单击 ThingSpeak 库，然后单击 Install 按钮。

- - 或者 - -

  1. 将 ZIP 文件（如下）下载到您的机器。
  2. 在 Arduino IDE 中，选择 Sketch/Include Library/Add Zip Library
  3. 导航到 ZIP 文件，然后单击“打开”

兼容硬件：

  • Arduino/Genuino 或兼容 WiFi Shield
  • Arduino/Genuino 或兼容 WiFi Shield 101（使用 WiFi101 库版本 0.13.0 或更早版本。）
  • Arduino/Genuino 或兼容以太网扩展板
  • Arduino/Genuino 或兼容 MKR ETH Shield
  • Arduino MKR1000
  • Arduino MKR1010
  • Arduino VIDOR 4000
  • Arduino GSM 14000
  • Arduino Uno WiFi Rev2
  • Arduino Yún（Rev1 和 Rev2）
  • ESP8266 直接编程（使用 SparkFun ESP8266 Thing - Dev Board 和 NodeMCU 1.0 模块测试）
  • ESP8266 通过 AT 命令
  • ESP32（使用 SparkFun ESP32 Thing 测试）

例子

该库包含按板类型组织的多个示例，以帮助您入门。这些示例可在 Arduino IDE 的“示例”>“ThingSpeak”菜单中访问。

  • ReadField：从 ThingSpeak 上的公共频道和私人频道读取。
  • WriteSingleField：将值写入 ThingSpeak 上的单个字段。
  • WriteMultipleFields：使用 ThingSpeak 在一次事务中将值写入多个字段和状态。
  • ReadMultipleFields：从 ThingSpeak 上的公共频道读取多个字段、状态、位置、创建时间戳的值
  • SecureConnect：使用上述功能并安全地连接到 ThingSpeak。

在这种情况下，使用 ESP8266 向一个带有递增数字的字段写入数据。

#include <ESP8266WiFi.h>
#include "secrets.h"
#include "ThingSpeak.h" // always include thingspeak header file after other header files and custom macros

bool begin (client) // defaults to ThingSpeak.com


    
      
    

      
    

    
  






范围
类型
描述






客户
客户 ＆
之前在 Sketch 中创建的 TCPClient






返回


始终返回 true。这不会验证传入的信息，也不会生成对 ThingSpeak 的任何调用。


评论


使用#define TS_ENABLE_SSL之前#include <thingspeak.h>，通过传递能够执行 SSL 的客户端来执行安全连接。请参阅下面有关安全连接的说明。


写入字段


将值写入 ThingSpeak 通道中的单个字段。


int writeField(channelNumber, field, value, writeAPIKey)


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




场地
无符号整数
要写入的通道内的字段编号（1-8）。




价值
整数
要写入的整数值（从 -32,768 至 32,767）。





长的
要写入的长值（从 -2,147,483,648 到 2,147,483,647）。





漂浮
要写入的浮点值（从 -999999000000 至 999999000000）。





细绳
要写入的字符串（UTF8 字符串）。ThingSpeak 将此字段限制为 255 个字节。





常量字符 *
要写入的字符数组（以零结尾）（UTF8）。ThingSpeak 将此字段限制为 255 个字节。




写入API密钥
常量字符 *
写入与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


评论


此方法将自动对特殊字符进行编码。请参阅下面有关特殊字符的注释。


写入字段


编写多字段更新。首先对要写入的每个字段调用 setField()。


int writeFields (channelNumber, writeAPIKey)	


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




写入API密钥
常量字符 *
写入与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


评论


此方法将自动对特殊字符进行编码。请参阅下面有关特殊字符的注释。


写入原始数据


将原始 POST 写入 ThingSpeak 频道。


int writeRaw (channelNumber, postMessage, writeAPIKey)	


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




发布消息
常量字符 *
以字符串形式写入 ThingSpeak 的原始 URL。请参阅https://thingspeak.com/docs/channels#update_feed上的文档。





细绳
以字符数组（以零结尾）形式写入 ThingSpeak 的原始 URL。请参阅https://thingspeak.com/docs/channels#update_feed上的文档。




写入API密钥
常量字符 *
写入与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


评论


此方法不会对帖子消息中的特殊字符进行编码。使用“%XX”URL 编码发送特殊字符。请参阅下面有关特殊字符的注释。


设置字段


设置将成为多字段更新一部分的单个字段的值。


int setField (field, value)


    
      
    

      
    

    
  






范围
类型
描述






场地
无符号整数
需要设置的通道内字段编号（1-8）




价值
整数
要写入的整数值（从 -32,768 至 32,767）。





长的
要写入的长值（从 -2,147,483,648 到 2,147,483,647）。





漂浮
要写入的浮点值（从 -999999000000 至 999999000000）。





细绳
要写入的字符串（UTF8 字符串）。ThingSpeak 将此字段限制为 255 个字节。





常量字符 *
要写入的字符数组（以零结尾）（UTF8）。ThingSpeak 将此字段限制为 255 个字节。






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


设置状态


设置多字段更新的状态。编写频道更新时，使用状态提供附加详细信息。此外，ThingTweet 应用程序可以使用状态向 Twitter 发送消息。


int setStatus (status)	


    
      
    

      
    

    
  






范围
类型
描述






地位
常量字符 *
要写入的字符串（UTF8）。ThingSpeak 将其限制为 255 个字节。





细绳
const 字符数组（以零结尾）。ThingSpeak 将其限制为 255 个字节。






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


设置纬度


设置多字段更新的纬度。


int setLatitude	(latitude)	


    
      
    

      
    

    
  






范围
类型
描述






纬度
漂浮
测量的纬度（北纬度，南纬度使用负值）






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


设置经度


设置多字段更新的经度。


int setLongitude (longitude)	


    
      
    

      
    

    
  






范围
类型
描述






经度
漂浮
测量经度（东经度，西经度使用负值）






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


设置海拔


设置多字段更新的高度。


int setElevation (elevation)	


    
      
    

      
    

    
  






范围
类型
描述






海拔
漂浮
测量海拔（海拔米数）






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


创建时间


设置多字段更新的创建日期。时间戳字符串必须采用 ISO 8601 格式。示例“2017-01-12 13:22:54”


int setCreatedAt (createdAt)


    
      
    

      
    

    
  






范围
类型
描述






创建于
细绳
期望的时间戳以字符串形式包含在频道更新中。





常量字符 *
所需的时间戳将作为字符数组（以零终止）包含在频道更新中。






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


评论


可以使用时区小时偏移参数设置时区。例如，东部标准时间的时间戳为：“2017-01-12 13:22:54-05”。如果未使用时区小时偏移参数，则假定为 UTC 时间。


设置TwitterTweet


设置用于发布更新的 Twitter 帐户和消息。


int setTwitterTweet	(twitter, tweet)	


    
      
    

      
    

    
  






范围
类型
描述






推特
细绳
Twitter 帐户名称作为字符串。





常量字符 *
Twitter 帐户名称作为字符数组（以零终止）。




鸣叫
细绳
Twitter 消息作为字符串（UTF-8）限制为 140 个字符。





常量字符 *
Twitter 消息作为字符数组（以零终止）限制为 140 个字符。






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


评论


在使用此功能之前，必须将 Twitter 帐户链接到您的 ThingSpeak 帐户。要链接您的 Twitter 帐户，请登录 ThingSpeak 并转到应用程序 -> ThingTweet，然后单击链接 Twitter 帐户。


读取字符串字段


从频道读取最新字符串。包含 readAPIKey 以读取私有频道。


String readStringField (channelNumber, field, readAPIKey)	


    
      
    

      
    

    
  


String readStringField (channelNumber, field)	


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




场地
无符号整数
要读取的通道内的字段编号（1-8）。




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


读取的值（UTF8 字符串），如果有错误则为空字符串。


读取浮点字段


从频道读取最新的浮点数。包括 readAPIKey 以读取私有频道。


float readFloatField (channelNumber, field, readAPIKey)	


    
      
    

      
    

    
  


float readFloatField (channelNumber, field)	


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




场地
无符号整数
要读取的通道内的字段编号（1-8）。




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


读取的值，如果字段为文本或出现错误，则为 0。使用 getLastReadStatus() 获取更具体的信息。请注意，NAN、INFINITY 和 -INFINITY 是有效结果。


读取长字段


从频道读取最新的长消息。包含 readAPIKey 以读取私人频道。


long readLongField (channelNumber, field, readAPIKey)	


    
      
    

      
    

    
  


long readLongField (channelNumber, field)	


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




场地
无符号整数
要读取的通道内的字段编号（1-8）。




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


读取的值，如果字段为文本或出现错误则为 0。使用 getLastReadStatus() 获取更具体的信息。


读取整数字段


从频道读取最新的 int。包含 readAPIKey 以读取私有频道。


int readIntField (channelNumber, field, readAPIKey)		


    
      
    

      
    

    
  


int readIntField (channelNumber, field)		


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




场地
无符号整数
要读取的通道内的字段编号（1-8）。




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


读取的值，如果字段为文本或出现错误，则为 0。使用 getLastReadStatus() 获取更具体的信息。如果返回的值超出 int 的范围，则结果未定义。


读取状态


从频道读取最新状态。包含 readAPIKey 以读取私人频道。


String readStatus (channelNumber, readAPIKey)	


    
      
    

      
    

    
  


String readStatus (channelNumber)


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


以字符串形式返回状态字段。


字符串 readCreatedAt()


读取与频道最新更新关联的创建时间戳。包含 readAPIKey 以读取私人频道。


String readCreatedAt (channelNumber, readAPIKey)


    
      
    

      
    

    
  


String readCreatedAt (channelNumber)	


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


以字符串形式返回创建时间戳。


读取原始数据


从频道读取原始响应。包含 readAPIKey 以读取私人频道。


String readRaw (channelNumber, URLSuffix, readAPIKey)	


    
      
    

      
    

    
  


String readRaw	(channelNumber, URLSuffix)


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




URL后缀
细绳
以字符串形式写入 ThingSpeak 的原始 URL。请参阅https://thingspeak.com/docs/channels#get_feed上的文档




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥。






返回


以字符串形式返回 HTTP 请求的原始响应。


读取多个字段


读取所有最新字段、状态、位置和创建时间戳；并将这些值存储在本地。使用getField下面提到的函数来获取存储的值。包括 readAPIKey 以读取私有频道。


int readMultipleFields (channelNumber, readAPIKey)


    
      
    

      
    

    
  


int readMultipleFields (channelNumber)


    
      
    

      
    

    
  






范围
类型
描述






频道编号
无符号长整型
通道编号




读取API密钥
常量字符 *
读取与渠道关联的 API 密钥。如果您与他人共享代码，请不要共享此密钥






返回


如果成功，则 HTTP 状态代码为 200。请参阅下面的返回代码以了解其他可能的返回值。


评论


由于内存限制，该功能在 Arduino Uno 中不可用。


获取字段作为字符串


从字段中获取存储的值作为字符串。调用后调用此方法readMultipleFields。


String getFieldAsString (field)


    
      
    

      
    

    
  






范围
类型
描述






场地
无符号整数
要读取的通道内的字段编号（1-8）。






返回


读取的值（UTF8 字符串），如果有错误则为空字符串，如果在 readMultipleFields() 之前调用则读取旧值（UTF8 字符串）。使用 getLastReadStatus() 获取更具体的信息。


评论


由于内存限制，该功能在 Arduino Uno 中不可用。


获取字段为浮点型


从字段中获取存储的值作为浮点数。调用后调用此方法readMultipleFields。


float getFieldAsFloat (field)


    
      
    

      
    

    
  






范围
类型
描述






场地
无符号整数
要读取的通道内的字段编号（1-8）。






返回


读取的值，如果字段为文本或存在错误，则为 0；如果在 readMultipleFields() 之前调用，则读取旧值。使用 getLastReadStatus() 获取更具体的信息。请注意，NAN、INFINITY 和 -INFINITY 是有效结果。


评论


由于内存限制，该功能在 Arduino Uno 中不可用。


获取字段为长整型


从字段中获取存储的值作为 Long。调用后调用此方法readMultipleFields。


long getFieldAsLong (field)


    
      
    

      
    

    
  






范围
类型
描述






场地
无符号整数
要读取的通道内的字段编号（1-8）。






返回


读取的值，如果字段为文本或有错误则为 0，如果在 readMultipleFields() 之前调用则读取旧值。使用 getLastReadStatus() 获取更具体的信息。


评论


由于内存限制，该功能在 Arduino Uno 中不可用。


获取字段为整数


从字段中获取存储的值作为 Int。调用后调用此方法readMultipleFields。


int getFieldAsInt (field)


    
      
    

      
    

    
  






范围
类型
描述






场地
无符号整数
要读取的通道内的字段编号（1-8）。






返回


读取的值，如果字段为文本或有错误则为 0，如果在 readMultipleFields() 之前调用则读取旧值。使用 getLastReadStatus() 获取更具体的信息。


评论


由于内存限制，该功能在 Arduino Uno 中不可用。


获取上次读取状态


获取上一次读取的状态。


int getLastReadStatus ()	


    
      
    

      
    

    
  


返回


请参阅下面的返回代码以了解其他可能的返回值。


返回代码






价值
意义






200
确定/成功




404
API 密钥不正确（或 ThingSpeak 服务器地址无效）




-101
值超出范围或字符串太长（> 255 个字符）




-201
指定的字段编号无效




-210
setField() 在 writeFields() 之前未被调用




-301
无法连接到 ThingSpeak




-302
写入 ThingSpeak 时发生意外失败




-303
无法解析响应




-304
等待服务器响应超时




-401
未插入点（最可能的原因是每 15 秒一次的速率限制）




0
其他错误






安全连接


安全连接到 ThingSpeak API 以使用上述特性和功能。


HTTPS


HTTPS 确保机密性和真实性。机密性：使用公钥加密的 SSL 加密。真实性：创建“信任”，设备知道它是否连接到实际的 api.thingkspeak.com，而不是欺骗。


用户草图要求


#define TS_ENABLE_SSL请务必使用#include <thingspeak.h>以执行安全连接。如果不使用，则默认连接将是不安全的 HTTP。


保密性不真实


情况 1：TS_ENABLE_SSL 宏已定义 + 客户端能够执行 SSL = 安全 HTTPS 连接

情况 2：TS_ENABLE_SSL 宏已定义 + 客户端不能执行 SSL = 默认 HTTP 连接，并向用户发送警告消息

情况 3：TS_ENABLE_SSL 宏未定义 + 客户端能够执行 SSL = 连接到 ThingSpeak 状态代码时出错并返回给用户

情况 4：TS_ENABLE_SSL 宏未定义 + 客户端不能执行 SSL = HTTP 连接


保密性+真实性


不同的客户端库执行真实性验证的方法也不同。

一些方法包括：根证书检查、证书指纹检查。

在调用函数之前执行指纹和/或证书检查begin()。

证书具有与之关联的到期日期，因此用户有责任获取更新的证书以建立机密性 + 真实性 HTTPS 连接。

请参阅使用 ESP8266 进行指纹检查 HTTPS 连接的 ReadMultipleFieldsSecure 示例。请参阅使用 ESP32 进行根证书检查 HTTPS 连接的 ReadMultipleFieldsSecure 示例。


特殊字符


某些字符在发送到 ThingSpeak 之前需要 '%XX' 样式 URL 编码。 writeField() 和 writeFields() 方法将自动执行编码。 writeRaw() 方法则不会。






特点
编码






“
%22




％
%25




&
%26




+
%2B




；
%3B






ThingSpeak 不接受控制字符（ASCII 值 0 到 31），并且会将其忽略。值超过 127 的扩展 ASCII 字符也将被忽略。

About

适用于 Arduino、ESP8266 和 ESP32 的 ThingSpeak 通信库

thingspeak.com

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • C++ 100.0%