EC-01G NBIOT+GPS Module

Module Source

Purchase link: https://item.taobao.com/item.htm?spm=a1z10.3-c-s.w4002-24271435830.11.47384853h0s6Zh&id=661208519683 Materials download: https://docs.ai-thinker.com/nb-iot

Specifications

Operating voltage: 3.0V-3.6V Operating current: IMAX = 170mA Module size: 14.4 x 24.7 MM Control method: UART

View Materials

The NBIOT module uses a network that provides data through an IoT SIM card. IoT SIM card link:

Telecom NB card Telecom NB IoT card Soldered/Plug-in Energy-saving low-power device for water/electricity/gas meters and door sensors

When using GPS positioning, do not use it indoors; indoor positioning is very difficult. You need to go outdoors for positioning.

For the rest, please refer to the official materials: https://docs.ai-thinker.com/nb-iot

Case 1: Connect to the Seniverse Weather Platform to Obtain Weather Data

Seniverse Weather Platform

1. Obtain Seniverse Weather For first-time use, you need to register first. Go to the official website: https://www.seniverse.com.

2. Log in to the console to obtain the private key (here I registered 1 key)

3. According to the materials provided by Anxinke Technology, complete the connection to the Seniverse Weather Platform. AT command sending steps: For command-related meanings, see the material [nb-iot series module AT command set v1.0.pdf]

API commands can be queried on the Seniverse Weather official website. Here are two API commands. (You can click the hyperlink text to jump to the relevant webpage)

In the Write Code section below, you need to change the private key. Please replace your_api_key with your own private key.

Pin Selection

Use UART2 (UART2-TX=P02, UART2-RX=P01)

Port to Project

Our goal is to port the example to the ESP32-S3 dev board. Complete driver code has been provided for you. Follow the steps below to complete the porting. For detailed instructions on creating folders and new .c and .h files, refer to section 1.4.2 in the [DHT11 Temperature and Humidity Sensor] chapter; we will not repeat it here. However, here we replace the file names bsp_dht11.c and bsp_dht11.h with bsp_ec01g.c and bsp_ec01g.h, and change the folder name to EC01G.

Write Code

WARNING

📌 In bsp_ec01g.h, modify the private key macro API_KEY to your own private key. And enter the city to query.

In the file bsp_ec01g.c, write the following code.

/*
 * LCSC-Openkits (LCKFB) software and hardware materials and related expansion board software and hardware materials are all open source on the official website.
 * Dev board official website: www.lckfb.com
 * Technical support resides on the forum; any technical questions are welcome for exchange and learning at any time.
 * LCKFB Forum: club.szlcsc.com
 * Follow our Bilibili account: [LCSC-Openkits (LCKFB)] to keep up with our latest updates!
 * We do not make money by selling boards; we take cultivating engineers as our mission.
 * Change Logs:
 * Date           Author       Notes
 * 2024-01-11     LCKFB-lp    first version
 */

#include "bsp_ec01g.h"
#include "stdio.h"
#include "string.h"

unsigned char EC01G_RX_BUFF[EC01G_RX_LEN_MAX];
unsigned char EC01G_RX_FLAG = 0;
unsigned int EC01G_RX_LEN = 0;

/*
        AT\r\n                //Test whether the device exists                        Returns OK means it exists
        AT+CFUN=1        //Disable airplane mode                                Returns OK means success
        AT+CEREG?        //Determine whether attached to network successfully                Returns +CEREG: 0,1 means successfully attached to network
        AT+HTTPCREATE=0,"http://116.62.81.138:80"        //Set command to create an http or https client instance                Returns OK means success
        AT+HTTPCON=0                //Connect to instance server 0        Returns OK means success
        AT+HTTPSEND=0,0,78,"/v3/weather/now.json?key=SIwiiHEWo6pPD42S5&location=beijing&language=en&unit=c"        //Send GET command to instance 0, address length is 78
        AT+HTTPDESTROY=0        //Disconnect   When +HTTPERR: 0,11 appears, you need to disconnect and then reconnect to the instance server



Convert the data returned by the API, the 7B227... after +HTTPRESPC: into string form

+HTTPRESPH: 0,200,396,Date: Fri, 02 Jun 2023 03:35:05 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 260
Connection: keep-alive
access-control-allow-origin: *
etag: W/"104-BAVuIqnZSk8TcsNHuRGYESoLzao"
x-powered-by: Express
x-ratelimit-limit: 20;w=60
x-ratelimit-remaining: 19
x-ratelimit-reset: 60.000
x-request-id: F2S6NvFKYBEUQ0zTbqlB
x-tenant-id: dbef859d-3503-45ff-ba2f-3e5f0f4de75d

+HTTPRESPC: 0,0,260,520,7B22726573756C7473223A5B7B226C6F636174696F6E223A7B226964223A2257583446425858464B45344622
2C226E616D65223A224265696A696E67222C22636F756E747279223A22434E222C2270617468223A224265696A696E672C4265694A696E67
2C4368696E61222C2274696D657A6F6E65223A22417369612F5368616E67686169222C2274696D657A6F6E655F6F6666736574223A222B30
383A3030227D2C226E6F77223A7B2274657874223A2253756E6E79222C22636F6465223A2230222C2274656D7065726174757265223A2232
38227D2C226C6173745F757064617465223A22323032332D30362D30325431313A31343A33382B30383A3030227D5D7D
*/

static void delay_ms(unsigned int ms)
{
    vTaskDelay(ms / portTICK_PERIOD_MS);
}
static void delay_us(unsigned int us)
{
    ets_delay_us(us);
}
static void delay_1ms(unsigned int ms)
{
    vTaskDelay(ms / portTICK_PERIOD_MS);
}
static void delay_1us(unsigned int us)
{
    ets_delay_us(us);
}

/************************************************************
 * Function Name: EC01G_USART_Init
 * Function Description: Initialization for connecting to EC01G
 * Parameters: bund=UART baud rate
 * Return Value: None
 * Notes: None
*************************************************************/
void EC01G_USART_Init(unsigned int bund)
{
    //Define UART configuration structure, must be initialized, otherwise it cannot work
    uart_config_t uart_config={0};

    uart_config.baud_rate = bund;                       //Configure baud rate
    uart_config.data_bits = UART_DATA_8_BITS;           //Configure data bits to 8
    uart_config.parity = UART_PARITY_DISABLE;           //Configure parity to none
    uart_config.stop_bits = UART_STOP_BITS_1;           //Configure stop bits to 1
    uart_config.flow_ctrl = UART_HW_FLOWCTRL_DISABLE;   //Disable hardware flow control

    //Load the above parameters into the UART1 registers
    uart_param_config(EC01G_USART, &uart_config);

    //Bind pins  TX=tx_pin RX=rx_pin RTS=Not used CTS=Not used
    uart_set_pin(EC01G_USART, GPIO_EC01G_TX, GPIO_EC01G_RX, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);

    //Install UART driver
    uart_driver_install(EC01G_USART, EC01G_RX_LEN_MAX, 200, 0, NULL, 0);
}

/******************************************************************
 * Function Name: EC01G_USART_Send_Bit
 * Function Description: Send a single character to the EC01G module
 * Function Parameters: ch=character
 * Function Return: None
 * Author: LC
 * Notes: None
******************************************************************/
void EC01G_USART_Send_Bit(unsigned char ch)
{
    uart_write_bytes(EC01G_USART, (const char*)&ch, 1);
}

/******************************************************************
 * Function Name: EC01G_USART_send_String
 * Function Description: Send a string to the EC01G module
 * Function Parameters: str=string to send
 * Function Return: None
 * Author: LC
 * Notes: None
******************************************************************/
void EC01G_USART_send_String(unsigned char *str)
{
    uart_write_bytes(EC01G_USART, (const char*)str, strlen( (const char*)str ));
}
//Clear data received by UART
/******************************************************************
 * Function Name: Clear_EC01G_RX_BUFF
 * Function Description: Clear data sent from EC01G
 * Function Parameters: None
 * Function Return: None
 * Author: LC
 * Notes: None
******************************************************************/
void Clear_EC01G_RX_BUFF(void)
{
    uart_flush(EC01G_USART);
    EC01G_RX_LEN = 0;
    EC01G_RX_FLAG = 0;
}

/******************************************************************
 * Function Name: EC01G_Send_Cmd
 * Function Description: Send commands to the EC01G module and check whether the EC01G module returns the desired data
 * Function Parameters: cmd=AT command to send        ack=desired response                waitms=time to wait for response                cnt=number of times to wait for response
 * Function Return: 1=got the desired response                0=did not get the desired response
 * Author: LC
 * Notes: None
******************************************************************/
char EC01G_Send_Cmd(char *cmd,char *ack,unsigned int waitms,unsigned char cnt)
{
        EC01G_USART_send_String((unsigned char*)cmd);//Send AT command
        while(cnt--)
        {
            //UART interrupt receives EC01G response
            if( EC01G_RX_FLAG == 1 )
            {
                EC01G_RX_FLAG = 0;
                EC01G_RX_LEN = 0;
                //Search whether desired data exists
                if( strstr((char*)EC01G_RX_BUFF, ack) != NULL )
                {
                        return 1;
                }
                //Clear received data
                Clear_EC01G_RX_BUFF();
            }
        //Time interval
        delay_1ms(waitms);
        }

        EC01G_RX_FLAG = 0;
        EC01G_RX_LEN = 0;
        return 0;
}

/******************************************************************
 * Function Name: EC01G_Init
 * Function Description: EC01G module initialization
 * Function Parameters: None
 * Function Return: None
 * Author: LC
 * Notes: ESP01S default baud rate is 9600
******************************************************************/
void EC01G_Init(void)
{
    EC01G_USART_Init(9600);//Default baud rate is 9600

    //Create UART2 receive task
    xTaskCreate(EC01G_USART_Handler, "EC01G_USART_Handler", 1024*2, NULL, tskIDLE_PRIORITY, NULL);
}

/******************************************************************
 * Function Name: EC01G_Seniverse_Init
 * Function Description: Configure the EC01G module to connect to the Seniverse Weather platform
 * Function Parameters: None
 * Function Return: 1=device not detected
 * Author: LC
 * Notes:
AT\r\n                            //Test whether the device exists                        Returns OK means it exists
AT+CFUN=1                    //Disable airplane mode                                Returns OK means success
AT+CEREG?                    //Determine whether attached to network successfully                Returns +CEREG: 0,1 means successfully attached to network
AT+HTTPCREATE=0,"http:  //116.62.81.138:80"        //Set command to create an http or https client instance                Returns OK means success
AT+HTTPCON=0                    //Connect to instance server 0        Returns OK means success
AT+HTTPSEND=0,0,78,"/v3/weather/now.json?key=SIwiiHEWo6pPD42S5&location=beijing&language=en&unit=c"        //Send GET command to instance 0, address length is 78
AT+HTTPDESTROY=0            //Disconnect   When +HTTPERR: 0,11 appears, you need to disconnect and then reconnect to the instance server
******************************************************************/
uint8_t EC01G_Seniverse_Init(void)
{
    uint8_t ret = 0;
    uint8_t i = 0;
    uint8_t send_buff[250]={0};

    //Test whether the device exists
    if( EC01G_Send_Cmd("AT\r\n", "OK", 1000,3) == 0 )
    {
            return 1;
    }

    //Disable airplane mode
    if( EC01G_Send_Cmd("AT+CFUN=1\r\n", "OK", 1000,3) == 0 )
    {
            return 2;
    }

    //Determine whether attached to network successfully
    if( EC01G_Send_Cmd("AT+CEREG?\r\n", "+CEREG: 0,1", 1000,3) == 0 )
    {
            delay_1ms(500);
            ret = EC01G_Send_Cmd("AT+CEREG?\r\n", "+CEREG: 0,1", 1000,3);
            if( ret == 0 )
            {
                    return 1;
            }
    }

    again:

    //If connected before, disconnect
    EC01G_Send_Cmd("AT+HTTPDESTROY=0\r\n", "OK", 500,1);
    //Clear received data
    Clear_EC01G_RX_BUFF();


    //Create an http client instance
    while( EC01G_Send_Cmd("AT+HTTPCREATE=0,\"http://116.62.81.138:80\"\r\n", "OK", 1000,3) == 0 )
    {
        #if DEBUG
            printf("AT+HTTPCREATE FAIL\r\n");
        #endif
        i++;
        if( i >= 3 )
        {
            return 2;
        }
        delay_ms(50);
        goto again;
    }

    i=0;

    //Connect to instance server 0 (default server 0)
    while( EC01G_Send_Cmd("AT+HTTPCON=0\r\n", "OK", 1000,3) == 0 )
    {
        #if DEBUG
            printf("AT+HTTPCON FAIL\r\n");
        #endif
        i++;
        if( i >= 3 ) return 3;

        delay_ms(50);
        goto again;
    }

    //Send API to get weather data
    sprintf((char*)send_buff, "AT+HTTPSEND=0,0,%d,%s\r\n", strlen(WEATHER_FACTS_API)-2, WEATHER_FACTS_API);
    if( EC01G_Send_Cmd((char*)send_buff, "OK", 1000,3) == 0 )
    {
        #if DEBUG
            printf("AT+HTTPSEND FAIL\r\n");

        #endif
        return 4;
    }

    return 0;
}

/******************************************************************
 * Function Name: Hex_To_Text
 * Function Description: Convert a hexadecimal string to a character string
 * Function Parameters: hex=hexadecimal string address    hex_len=     text=address to save to
 * Function Return: None
 * Author: LC
 * Notes: None
******************************************************************/
void Hex_To_Text(char *hex, char *text)
{
    char buff[200]={0};
    int string_length = strlen((char*)hex) / 2;
    int i = 0;

    // Convert every two characters into one byte and copy it to the converted string
    for (i = 0; i < string_length; i++) {
        char HEX[3];
        memcpy(HEX, &hex[i * 2], 2);
        HEX[2] = '\0';
        text[i] = strtol(HEX, NULL, 16);
    }
    text[i]='\0';
}

/******************************************************************
 * Function Name: Search_Data
 * Function Description: Search for corresponding data
 * Function Parameters: original_data=original data   weather_data=data to save  find_what=data header to find
 * Function Return: 0=search failed   1=search successful
 * Author: LC
 * Notes: None
******************************************************************/
uint8_t Search_Data(char *original_data, char * weather_data, char *find_what)
{
    char *buff;
    uint16_t i = 0;
    if( strstr(original_data, find_what) != NULL )
    {
        //Find the starting address of the content
        buff = strstr(original_data, find_what);
        //Filter out find_what content
        buff += strlen(find_what);
        //Find the index of '"'
        while( buff[i] != '"' )
        {
            i++;
        }
        //Copy a string of length i from buff to weather_data
        strncpy(weather_data, buff, i);
        //strncpy does not null-terminate, need to add it manually
        weather_data[i+1] = '\0';
        return 1;
    }
    return 0;
}

/******************************************************************
 * Function Name: Weather_Data_Analysis
 * Function Description: Parse weather data format.
 * Function Parameters: original_data=original JSON format data  weather_data=parsed data save address
 * Function Return: None
 * Author: LC
 * Notes: Original JSON format data is shown below
{"results":[{"location":{"id":"WS10730EM8EV","name":"Shenzhen","country":"CN","path":
"Shenzhen,Shenzhen,Guangdong,China","timezone":"Asia/Shanghai","timezone_offset":
"+08:00"},"now":{"text":"Sunny","code":"0","temperature":"32"},"last_update":"2023-06-02T16:10:15+08:00"}]}
******************************************************************/
void Weather_Data_Analysis(char *original_data, WEATHER_DATA* weather_data)
{
    //Search for city
    Search_Data(original_data,weather_data->city,"name\":\"");
    //Search for country
    Search_Data(original_data,weather_data->country,"country\":\"");
    //Search for specific address
    Search_Data(original_data,weather_data->path,"path\":\"");
    //Search for weather status
    Search_Data(original_data,weather_data->weather,"text\":\"");
    //Search for weather code
    Search_Data(original_data,weather_data->weather_code,"code\":\"");
    //Search for current temperature
    Search_Data(original_data,weather_data->temperature,"temperature\":\"");
    //Search for update time
    Search_Data(original_data,weather_data->last_update,"last_update\":\"");
}

/******************************************************************
 * Function Name: Get_Weather_Data
 * Function Description: Get weather data
 * Function Parameters: data=structure address to save all weather data
 * Function Return: None
 * Author: LC
 * Notes: None
******************************************************************/
void Get_Weather_Data(WEATHER_DATA* data)
{
    uint16_t outtime = 5000;//5-second timeout
    uint16_t i = 0;
    unsigned char send_buff[250]={0};
    char parse_buff[1024]={0};
    char *rev_buff=0;

    //Clear received data
        Clear_EC01G_RX_BUFF();
    //Organize weather data API
    sprintf((char*)send_buff, "AT+HTTPSEND=0,0,%d,%s\r\n", strlen(WEATHER_FACTS_API)-2, WEATHER_FACTS_API);
    //Send command
    EC01G_USART_send_String(send_buff);

    //Receive data
    while( outtime-- )
    {
        delay_1ms(50);
        if( EC01G_RX_FLAG == 1 )
        {
            EC01G_RX_FLAG = 0;
            //If received correctly
            if( strstr((const char*)EC01G_RX_BUFF, "+HTTPRESPC:")  != NULL )
            {
                //Save data address
                rev_buff = strstr((const char*)EC01G_RX_BUFF, "+HTTPRESPC:");
                break;
            }
        }
    }

    //Filter out unneeded data
    rev_buff+=11;   //Filter out +HTTPRESPC:
    while( i < 4 )//Filter out 4 commas
    {
        if( *rev_buff == ',' )
        {
            i++;
        }
        rev_buff++;
    }

    //Convert hexadecimal string to character string
    Hex_To_Text(rev_buff, parse_buff);

    //Parse data and save to data
    Weather_Data_Analysis(parse_buff, data);
}

/******************************************************************
 * Function Name: EC01G_USART_Handler
 * Function Description: UART interrupt service function for connecting to EC01G
 * Function Parameters: None
 * Function Return: None
 * Author: LC
 * Notes: None
******************************************************************/
void EC01G_USART_Handler(void)
{
    while(1)
    {
        //Receive data
        EC01G_RX_LEN = uart_read_bytes(EC01G_USART, EC01G_RX_BUFF, EC01G_RX_LEN_MAX-1, 500 / portTICK_PERIOD_MS);

        if( EC01G_RX_LEN > 0 )  // Receive buffer is not empty
        {
            EC01G_RX_BUFF[EC01G_RX_LEN] = '\0';     //Append '\0' to the end of the string
            EC01G_RX_FLAG = 1;                      // Reception complete

            #if DEBUG //Test, view what data was received
                printf("%s\r\n", EC01G_RX_BUFF);
            #endif
        }
        delay_ms(500);
    }

In the file bsp_ec01g.h, write the following code.

/*
 * LCSC-Openkits (LCKFB) software and hardware materials and related expansion board software and hardware materials are all open source on the official website.
 * Dev board official website: www.lckfb.com
 * Technical support resides on the forum; any technical questions are welcome for exchange and learning at any time.
 * LCKFB Forum: club.szlcsc.com
 * Follow our Bilibili account: [LCSC-Openkits (LCKFB)] to keep up with our latest updates!
 * We do not make money by selling boards; we take cultivating engineers as our mission.
 * Change Logs:
 * Date           Author       Notes
 * 2024-01-11     LCKFB-lp    first version
 */
#ifndef _BSP_EC01G_H_
#define _BSP_EC01G_H_

#include <stdio.h>
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/uart.h"
#include "driver/gpio.h"
#include "driver/i2c.h"
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "freertos/queue.h"
#include <inttypes.h>
#include "sdkconfig.h"
#include "driver/gpio.h"
#include "esp_log.h"
#include "rom/ets_sys.h"
#include "esp_system.h"
#include "driver/gpio.h"
#include "driver/spi_master.h"
#include "driver/spi_common.h"
#include "hal/gpio_types.h"
#include "string.h"

//Whether to enable UART debugging to view WIFI echo data
#define     DEBUG   1

/****************************   Seniverse Weather     ****************************/
//Private key (needs to be modified to your own key!)
#define API_KEY                "SpUFyXp2YvP12yxQR"

//City to query (Enter city pinyin, free version only supports some cities)
#define QUERIED_CITY    "shenzhen"

//Weather facts API                 "/v3/weather/now.json?key=your_api_key&location=beijing&language=zh-Hans&unit=c"
#define WEATHER_FACTS_FRONT             "\"/v3/weather/now.json?key="
#define WEATHER_FACTS_MIDDLE            "&location="
#define WEATHER_FACTS_BACK              "&language=en&unit=c\""
//Query weather facts API
#define WEATHER_FACTS_API ( WEATHER_FACTS_FRONT  API_KEY  WEATHER_FACTS_MIDDLE  QUERIED_CITY  WEATHER_FACTS_BACK)

//Future weather forecast API   "/v3/weather/daily.json?key=your_api_key&location=beijing&language=zh-Hans&unit=c&start=0&days=5"
#define FUTURE_WEATHER_FRONT             "\"/v3/weather/daily.json?key="
#define FUTURE_WEATHER_MIDDLE            "&location="
#define FUTURE_WEATHER_BACK              "&language=en&unit=c&start=0&days=5\""
//Future weather forecast API
#define FUTURE_WEATHER_API ( FUTURE_WEATHER_FRONT  API_KEY  FUTURE_WEATHER_MIDDLE  QUERIED_CITY  FUTURE_WEATHER_BACK)

//Received data save address
typedef struct{
    char  city[20];         //Queried city
    char country[20];       //Queried country
    char path[50];          //Specific address (city city province country, example: Shenzhen,Shenzhen,Guangdong,China)
    char weather[10];       //Weather status
    char weather_code[5];   //Weather code
    char temperature[5];    //Temperature
    char last_update[50];   //Weather data update time
}WEATHER_DATA;

/****************************   UART Configuration    ****************************/
#define GPIO_EC01G_TX        2              // UART TX pin
#define GPIO_EC01G_RX        1              // UART RX pin

#define EC01G_USART          UART_NUM_2     // UART2

#define EC01G_RX_LEN_MAX     2096           //Maximum UART receive length

void EC01G_Init(void);
uint8_t EC01G_Seniverse_Init(void);
void Get_Weather_Data(WEATHER_DATA* data);
void EC01G_USART_Handler(void);

#endif

Porting Verification

Write into main.c:

/*
 * LCSC-Openkits (LCKFB) software and hardware materials and related expansion board software and hardware materials are all open source on the official website.
 * Dev board official website: www.lckfb.com
 * Technical support resides on the forum; any technical questions are welcome for exchange and learning at any time.
 * LCKFB Forum: club.szlcsc.com
 * Follow our Bilibili account: [LCSC-Openkits (LCKFB)] to keep up with our latest updates!
 * We do not make money by selling boards; we take cultivating engineers as our mission.
 * Change Logs:
 * Date           Author       Notes
 * 2024-01-11     LCKFB-lp    first version
 */
#include <stdio.h>
#include "bsp_ec01g.h"
#include "string.h"
#include "esp_private/esp_task_wdt.h"
#include "esp_private/esp_task_wdt_impl.h"

int app_main(void)
{
        WEATHER_DATA weather_data={0};
        esp_task_wdt_deinit();
        printf("Start......\r\n");

        EC01G_Init();
        EC01G_Seniverse_Init();

        //Wait for previous UART data reception to complete
        vTaskDelay(3000 / portTICK_PERIOD_MS);

        printf("\r\n\r\nagain rev\r\n\r\n");
        //Get weather data and save it to the weather_data structure
        Get_Weather_Data(&weather_data);

        printf("city = %s\r\n", weather_data.city );
        printf("country = %s\r\n", weather_data.country );
        printf("path = %s\r\n", weather_data.path );
        printf("weather = %s\r\n", weather_data.weather );
        printf("weather_code = %s\r\n", weather_data.weather_code );
        printf("temperature = %s\r\n", weather_data.temperature );
        printf("last_update = %s\r\n", weather_data.last_update );

        while(1)
        {
                vTaskDelay(500 / portTICK_PERIOD_MS);
        }
}

Power-on behavior:

Driver code:

File Download

📌 Materials Download Center (click to jump)

📌 In the Materials Download Center -> Module Porting Materials Download, inside the compressed package of this chapter.