examples: Standardise naming of files, symbols, etc. in examples

* Use "example" in all example function & variable names,
  ie use i2c_example_xxx instead of i2c_xxx for example functions.
  Closes #198 espressif/esp-idf#198
* Mark example functions, etc. static
* Replace uses of "test" & "demo" with "example"
* Split the UART example into two
* Rename "main" example files to end with "_main.c" for disambiguation

examples/README.md

@@ -32,4 +32,7 @@ In addition, here are some tips for creating good examples:
 
 * A good example is documented and the basic options can be configured.
 * A good example does not contain a lot of code. If there is a lot of generic code in the example, consider refactoring that code into a standalone component and then use the component's API in your example.
+* Names (of files, functions, variables, etc.) inside examples should be distinguishable from names of other parts of IDF (ideally, use `example` in names.)
+* Functions and variables used inside examples should be declared static where possible.
+* Examples should demonstrate one distinct thing each. Avoid multi-purposed "demo" examples, split these into multiple examples instead.
 * Examples must be licensed under the Apache License 2.0 or (preferably for examples) if possible you can declare the example to be Public Domain / Creative Commons Zero.

examples/bluetooth/blufi/main/blufi_demo.h → examples/bluetooth/blufi/main/blufi_example.h

@@ -1,10 +1,8 @@
-#ifndef __BLUFI_DEMO_H__
-#define __BLUFI_DEMO_H__
+#pragma once
 
-
-#define BLUFI_DEMO_TAG "BLUFI_DEMO"
-#define BLUFI_INFO(fmt, ...)   ESP_LOGI(BLUFI_DEMO_TAG, fmt, ##__VA_ARGS__) 
-#define BLUFI_ERROR(fmt, ...)  ESP_LOGE(BLUFI_DEMO_TAG, fmt, ##__VA_ARGS__) 
+#define BLUFI_EXAMPLE_TAG "BLUFI_EXAMPLE"
+#define BLUFI_INFO(fmt, ...)   ESP_LOGI(BLUFI_EXAMPLE_TAG, fmt, ##__VA_ARGS__) 
+#define BLUFI_ERROR(fmt, ...)  ESP_LOGE(BLUFI_EXAMPLE_TAG, fmt, ##__VA_ARGS__) 
 
 void blufi_dh_negotiate_data_handler(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free);
 int blufi_aes_encrypt(uint8_t iv8, uint8_t *crypt_data, int crypt_len);
@@ -13,5 +11,3 @@ uint16_t blufi_crc_checksum(uint8_t iv8, uint8_t *data, int len);
 
 int blufi_security_init(void);
 void blufi_security_deinit(void);
-
-#endif /* __BLUFI_DEMO_H__ */

examples/bluetooth/blufi/main/blufi_main.c → examples/bluetooth/blufi/main/blufi_example_main.c

@@ -30,19 +30,19 @@
 #include "esp_gap_ble_api.h"
 #include "esp_bt_main.h"
 #include "esp_bt_device.h"
-#include "blufi_demo.h"
+#include "blufi_example.h"
 
-static void blufi_event_callback(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param);
+static void example_event_callback(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param);
 
 #define BLUFI_DEVICE_NAME            "BLUFI_DEVICE"
-static uint8_t blufi_service_uuid128[32] = {
+static uint8_t example_service_uuid128[32] = {
     /* LSB <--------------------------------------------------------------------------------> MSB */
     //first uuid, 16bit, [12],[13] is the value
     0xfb, 0x34, 0x9b, 0x5f, 0x80, 0x00, 0x00, 0x80, 0x00, 0x10, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00,
 };
 
 //static uint8_t test_manufacturer[TEST_MANUFACTURER_DATA_LEN] =  {0x12, 0x23, 0x45, 0x56};
-static esp_ble_adv_data_t blufi_adv_data = {
+static esp_ble_adv_data_t example_adv_data = {
     .set_scan_rsp = false,
     .include_name = true,
     .include_txpower = true,
@@ -54,11 +54,11 @@ static esp_ble_adv_data_t blufi_adv_data = {
     .service_data_len = 0,
     .p_service_data = NULL,
     .service_uuid_len = 16,
-    .p_service_uuid = blufi_service_uuid128,
+    .p_service_uuid = example_service_uuid128,
     .flag = 0x6,
 };
 
-static esp_ble_adv_params_t blufi_adv_params = {
+static esp_ble_adv_params_t example_adv_params = {
     .adv_int_min        = 0x100,
     .adv_int_max        = 0x100,
     .adv_type           = ADV_TYPE_IND,
@@ -88,7 +88,7 @@ static uint8_t gl_sta_bssid[6];
 static uint8_t gl_sta_ssid[32];
 static int gl_sta_ssid_len;
 
-static esp_err_t event_handler(void *ctx, system_event_t *event)
+static esp_err_t example_net_event_handler(void *ctx, system_event_t *event)
 {
     wifi_mode_t mode;
 
@@ -146,32 +146,32 @@ static void initialise_wifi(void)
 {
     tcpip_adapter_init();
     wifi_event_group = xEventGroupCreate();
-    ESP_ERROR_CHECK( esp_event_loop_init(event_handler, NULL) );
+    ESP_ERROR_CHECK( esp_event_loop_init(example_net_event_handler, NULL) );
     wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
     ESP_ERROR_CHECK( esp_wifi_init(&cfg) );
     ESP_ERROR_CHECK( esp_wifi_set_storage(WIFI_STORAGE_RAM) );
     ESP_ERROR_CHECK( esp_wifi_set_mode(WIFI_MODE_STA) );
     ESP_ERROR_CHECK( esp_wifi_start() );
 }
 
-static esp_blufi_callbacks_t blufi_callbacks = {
-    .event_cb = blufi_event_callback,
+static esp_blufi_callbacks_t example_callbacks = {
+    .event_cb = example_event_callback,
     .negotiate_data_handler = blufi_dh_negotiate_data_handler,
     .encrypt_func = blufi_aes_encrypt,
     .decrypt_func = blufi_aes_decrypt,
     .checksum_func = blufi_crc_checksum,
 };
 
-static void blufi_event_callback(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param)
+static void example_event_callback(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param)
 {
     /* actually, should post to blufi_task handle the procedure,
-     * now, as a demo, we do simplely */
+     * now, as a example, we do it more simply */
     switch (event) {
     case ESP_BLUFI_EVENT_INIT_FINISH:
         BLUFI_INFO("BLUFI init finish\n");
 
         esp_ble_gap_set_device_name(BLUFI_DEVICE_NAME);
-        esp_ble_gap_config_adv_data(&blufi_adv_data);
+        esp_ble_gap_config_adv_data(&example_adv_data);
         break;
     case ESP_BLUFI_EVENT_DEINIT_FINISH:
         BLUFI_INFO("BLUFI init finish\n");
@@ -184,7 +184,7 @@ static void blufi_event_callback(esp_blufi_cb_event_t event, esp_blufi_cb_param_
         break;
     case ESP_BLUFI_EVENT_BLE_DISCONNECT:
         BLUFI_INFO("BLUFI ble disconnect\n");
-        esp_ble_gap_start_advertising(&blufi_adv_params);
+        esp_ble_gap_start_advertising(&example_adv_params);
         break;
     case ESP_BLUFI_EVENT_SET_WIFI_OPMODE:
         BLUFI_INFO("BLUFI Set WIFI opmode %d\n", param->wifi_mode.op_mode);
@@ -297,11 +297,11 @@ static void blufi_event_callback(esp_blufi_cb_event_t event, esp_blufi_cb_param_
     }
 }
 
-static void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param)
+static void example_gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param)
 {
     switch (event) {
     case ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT:
-        esp_ble_gap_start_advertising(&blufi_adv_params);
+        esp_ble_gap_start_advertising(&example_adv_params);
         break;
     default:
         break;
@@ -340,8 +340,8 @@ void app_main()
     BLUFI_INFO("BLUFI VERSION %04x\n", esp_blufi_get_version());
 
     blufi_security_init();
-    esp_ble_gap_register_callback(gap_event_handler);
+    esp_ble_gap_register_callback(example_gap_event_handler);
 
-    esp_blufi_register_callbacks(&blufi_callbacks);
+    esp_blufi_register_callbacks(&example_callbacks);
     esp_blufi_profile_init();
 }

examples/bluetooth/blufi/main/blufi_security.c

@@ -29,7 +29,7 @@
 #include "esp_bt_defs.h"
 #include "esp_gap_ble_api.h"
 #include "esp_bt_main.h"
-#include "blufi_demo.h"
+#include "blufi_example.h"
 
 #include "mbedtls/aes.h"
 #include "mbedtls/dhm.h"

examples/ethernet/ethernet/main/ethernet_main.c → examples/ethernet/ethernet/main/ethernet_example_main.c

@@ -34,7 +34,7 @@
 #include "driver/gpio.h"
 #include "tlk110_phy.h"
 
-static const char *TAG = "eth_demo";
+static const char *TAG = "eth_example";
 
 #define DEFAULT_PHY_CONFIG (AUTO_MDIX_ENABLE|AUTO_NEGOTIATION_ENABLE|AN_1|AN_0|LED_CFG)
 #define PIN_PHY_POWER 17

examples/peripherals/gpio/main/gpio_test.c → examples/peripherals/gpio/main/gpio_example_main.c

@@ -41,13 +41,13 @@
 
 static xQueueHandle gpio_evt_queue = NULL;
 
-void IRAM_ATTR gpio_isr_handler(void* arg)
+static void IRAM_ATTR gpio_isr_handler(void* arg)
 {
     uint32_t gpio_num = (uint32_t) arg;
     xQueueSendFromISR(gpio_evt_queue, &gpio_num, NULL);
 }
 
-void gpio_task_example(void* arg)
+static void gpio_task_example(void* arg)
 {
     uint32_t io_num;
     for(;;) {
@@ -62,7 +62,7 @@ void app_main()
     gpio_config_t io_conf;
     //disable interrupt
     io_conf.intr_type = GPIO_PIN_INTR_DISABLE;
-    //set as output mode        
+    //set as output mode
     io_conf.mode = GPIO_MODE_OUTPUT;
     //bit mask of the pins that you want to set,e.g.GPIO18/19
     io_conf.pin_bit_mask = GPIO_OUTPUT_PIN_SEL;

examples/peripherals/i2c/main/i2c_test.c → examples/peripherals/i2c/main/i2c_example_main.c

@@ -47,18 +47,18 @@
 #define RW_TEST_LENGTH       129  /*!<Data length for r/w test, any value from 0-DATA_LENGTH*/
 #define DELAY_TIME_BETWEEN_ITEMS_MS   1234 /*!< delay time between different test items */
 
-#define I2C_SLAVE_SCL_IO     26    /*!<gpio number for i2c slave clock  */
-#define I2C_SLAVE_SDA_IO     25    /*!<gpio number for i2c slave data */
-#define I2C_SLAVE_NUM I2C_NUM_0    /*!<I2C port number for slave dev */
-#define I2C_SLAVE_TX_BUF_LEN  (2*DATA_LENGTH) /*!<I2C slave tx buffer size */
-#define I2C_SLAVE_RX_BUF_LEN  (2*DATA_LENGTH) /*!<I2C slave rx buffer size */
+#define I2C_EXAMPLE_SLAVE_SCL_IO     26    /*!<gpio number for i2c slave clock  */
+#define I2C_EXAMPLE_SLAVE_SDA_IO     25    /*!<gpio number for i2c slave data */
+#define I2C_EXAMPLE_SLAVE_NUM I2C_NUM_0    /*!<I2C port number for slave dev */
+#define I2C_EXAMPLE_SLAVE_TX_BUF_LEN  (2*DATA_LENGTH) /*!<I2C slave tx buffer size */
+#define I2C_EXAMPLE_SLAVE_RX_BUF_LEN  (2*DATA_LENGTH) /*!<I2C slave rx buffer size */
 
-#define I2C_MASTER_SCL_IO    19    /*!< gpio number for I2C master clock */
-#define I2C_MASTER_SDA_IO    18    /*!< gpio number for I2C master data  */
-#define I2C_MASTER_NUM I2C_NUM_1   /*!< I2C port number for master dev */
-#define I2C_MASTER_TX_BUF_DISABLE   0   /*!< I2C master do not need buffer */
-#define I2C_MASTER_RX_BUF_DISABLE   0   /*!< I2C master do not need buffer */
-#define I2C_MASTER_FREQ_HZ    100000     /*!< I2C master clock frequency */
+#define I2C_EXAMPLE_MASTER_SCL_IO    19    /*!< gpio number for I2C master clock */
+#define I2C_EXAMPLE_MASTER_SDA_IO    18    /*!< gpio number for I2C master data  */
+#define I2C_EXAMPLE_MASTER_NUM I2C_NUM_1   /*!< I2C port number for master dev */
+#define I2C_EXAMPLE_MASTER_TX_BUF_DISABLE   0   /*!< I2C master do not need buffer */
+#define I2C_EXAMPLE_MASTER_RX_BUF_DISABLE   0   /*!< I2C master do not need buffer */
+#define I2C_EXAMPLE_MASTER_FREQ_HZ    100000     /*!< I2C master clock frequency */
 
 #define BH1750_SENSOR_ADDR  0x23    /*!< slave address for BH1750 sensor */
 #define BH1750_CMD_START    0x23    /*!< Command to set measure mode */
@@ -81,7 +81,7 @@ xSemaphoreHandle print_mux;
  * --------|--------------------------|----------------------|--------------------|------|
  *
  */
-esp_err_t i2c_master_read_slave(i2c_port_t i2c_num, uint8_t* data_rd, size_t size)
+static esp_err_t i2c_example_master_read_slave(i2c_port_t i2c_num, uint8_t* data_rd, size_t size)
 {
     if (size == 0) {
         return ESP_OK;
@@ -110,7 +110,7 @@ esp_err_t i2c_master_read_slave(i2c_port_t i2c_num, uint8_t* data_rd, size_t siz
  * --------|---------------------------|----------------------|------|
  *
  */
-esp_err_t i2c_master_write_slave(i2c_port_t i2c_num, uint8_t* data_wr, size_t size)
+static esp_err_t i2c_example_master_write_slave(i2c_port_t i2c_num, uint8_t* data_wr, size_t size)
 {
     i2c_cmd_handle_t cmd = i2c_cmd_link_create();
     i2c_master_start(cmd);
@@ -135,7 +135,7 @@ esp_err_t i2c_master_write_slave(i2c_port_t i2c_num, uint8_t* data_wr, size_t si
  * | start | slave_addr + rd_bit + ack | read 1 byte + ack  | read 1 byte + nack | stop |
  * --------|---------------------------|--------------------|--------------------|------|
  */
-esp_err_t i2c_master_sensor_test(i2c_port_t i2c_num, uint8_t* data_h, uint8_t* data_l)
+static esp_err_t i2c_example_master_sensor_test(i2c_port_t i2c_num, uint8_t* data_h, uint8_t* data_l)
 {
     i2c_cmd_handle_t cmd = i2c_cmd_link_create();
     i2c_master_start(cmd);
@@ -166,42 +166,46 @@ esp_err_t i2c_master_sensor_test(i2c_port_t i2c_num, uint8_t* data_h, uint8_t* d
 /**
  * @brief i2c master initialization
  */
-void i2c_master_init()
+static void i2c_example_master_init()
 {
-    int i2c_master_port = I2C_MASTER_NUM;
+    int i2c_master_port = I2C_EXAMPLE_MASTER_NUM;
     i2c_config_t conf;
     conf.mode = I2C_MODE_MASTER;
-    conf.sda_io_num = I2C_MASTER_SDA_IO;
+    conf.sda_io_num = I2C_EXAMPLE_MASTER_SDA_IO;
     conf.sda_pullup_en = GPIO_PULLUP_ENABLE;
-    conf.scl_io_num = I2C_MASTER_SCL_IO;
+    conf.scl_io_num = I2C_EXAMPLE_MASTER_SCL_IO;
     conf.scl_pullup_en = GPIO_PULLUP_ENABLE;
-    conf.master.clk_speed = I2C_MASTER_FREQ_HZ;
+    conf.master.clk_speed = I2C_EXAMPLE_MASTER_FREQ_HZ;
     i2c_param_config(i2c_master_port, &conf);
-    i2c_driver_install(i2c_master_port, conf.mode, I2C_MASTER_RX_BUF_DISABLE, I2C_MASTER_TX_BUF_DISABLE, 0);
+    i2c_driver_install(i2c_master_port, conf.mode,
+                       I2C_EXAMPLE_MASTER_RX_BUF_DISABLE,
+                       I2C_EXAMPLE_MASTER_TX_BUF_DISABLE, 0);
 }
 
 /**
  * @brief i2c slave initialization
  */
-void i2c_slave_init()
+static void i2c_example_slave_init()
 {
-    int i2c_slave_port = I2C_SLAVE_NUM;
+    int i2c_slave_port = I2C_EXAMPLE_SLAVE_NUM;
     i2c_config_t conf_slave;
-    conf_slave.sda_io_num = I2C_SLAVE_SDA_IO;
+    conf_slave.sda_io_num = I2C_EXAMPLE_SLAVE_SDA_IO;
     conf_slave.sda_pullup_en = GPIO_PULLUP_ENABLE;
-    conf_slave.scl_io_num = I2C_SLAVE_SCL_IO;
+    conf_slave.scl_io_num = I2C_EXAMPLE_SLAVE_SCL_IO;
     conf_slave.scl_pullup_en = GPIO_PULLUP_ENABLE;
     conf_slave.mode = I2C_MODE_SLAVE;
     conf_slave.slave.addr_10bit_en = 0;
     conf_slave.slave.slave_addr = ESP_SLAVE_ADDR;
     i2c_param_config(i2c_slave_port, &conf_slave);
-    i2c_driver_install(i2c_slave_port, conf_slave.mode, I2C_SLAVE_RX_BUF_LEN, I2C_SLAVE_TX_BUF_LEN, 0);
+    i2c_driver_install(i2c_slave_port, conf_slave.mode,
+                       I2C_EXAMPLE_SLAVE_RX_BUF_LEN,
+                       I2C_EXAMPLE_SLAVE_TX_BUF_LEN, 0);
 }
 
 /**
  * @brief test function to show buffer
  */
-void disp_buf(uint8_t* buf, int len)
+static void disp_buf(uint8_t* buf, int len)
 {
     int i;
     for (i = 0; i < len; i++) {
@@ -213,7 +217,7 @@ void disp_buf(uint8_t* buf, int len)
     printf("\n");
 }
 
-void i2c_test_task(void* arg)
+static void i2c_test_task(void* arg)
 {
     int i = 0;
     int ret;
@@ -224,7 +228,7 @@ void i2c_test_task(void* arg)
     uint8_t sensor_data_h, sensor_data_l;
 
     while (1) {
-        ret = i2c_master_sensor_test( I2C_MASTER_NUM, &sensor_data_h, &sensor_data_l);
+        ret = i2c_example_master_sensor_test( I2C_EXAMPLE_MASTER_NUM, &sensor_data_h, &sensor_data_l);
         xSemaphoreTake(print_mux, portMAX_DELAY);
         printf("*******************\n");
         printf("TASK[%d]  MASTER READ SENSOR( BH1750 )\n", task_idx);
@@ -243,12 +247,12 @@ void i2c_test_task(void* arg)
         for (i = 0; i < DATA_LENGTH; i++) {
             data[i] = i;
         }
-        size_t d_size = i2c_slave_write_buffer(I2C_SLAVE_NUM, data, RW_TEST_LENGTH, 1000 / portTICK_RATE_MS);
+        size_t d_size = i2c_slave_write_buffer(I2C_EXAMPLE_SLAVE_NUM, data, RW_TEST_LENGTH, 1000 / portTICK_RATE_MS);
         if (d_size == 0) {
             printf("i2c slave tx buffer full\n");
-            ret = i2c_master_read_slave(I2C_MASTER_NUM, data_rd, DATA_LENGTH);
+            ret = i2c_example_master_read_slave(I2C_EXAMPLE_MASTER_NUM, data_rd, DATA_LENGTH);
         } else {
-            ret = i2c_master_read_slave(I2C_MASTER_NUM, data_rd, RW_TEST_LENGTH);
+            ret = i2c_example_master_read_slave(I2C_EXAMPLE_MASTER_NUM, data_rd, RW_TEST_LENGTH);
         }
         xSemaphoreTake(print_mux, portMAX_DELAY);
         printf("*******************\n");
@@ -270,9 +274,9 @@ void i2c_test_task(void* arg)
             data_wr[i] = i + 10;
         }
         //we need to fill the slave buffer so that master can read later
-        ret = i2c_master_write_slave( I2C_MASTER_NUM, data_wr, RW_TEST_LENGTH);
+        ret = i2c_example_master_write_slave( I2C_EXAMPLE_MASTER_NUM, data_wr, RW_TEST_LENGTH);
         if (ret == ESP_OK) {
-            size = i2c_slave_read_buffer( I2C_SLAVE_NUM, data, RW_TEST_LENGTH, 1000 / portTICK_RATE_MS);
+            size = i2c_slave_read_buffer( I2C_EXAMPLE_SLAVE_NUM, data, RW_TEST_LENGTH, 1000 / portTICK_RATE_MS);
         }
         xSemaphoreTake(print_mux, portMAX_DELAY);
         printf("*******************\n");
@@ -294,8 +298,8 @@ void i2c_test_task(void* arg)
 void app_main()
 {
     print_mux = xSemaphoreCreateMutex();
-    i2c_slave_init();
-    i2c_master_init();
+    i2c_example_slave_init();
+    i2c_example_master_init();
 
     xTaskCreate(i2c_test_task, "i2c_test_task_0", 1024 * 2, (void* ) 0, 10, NULL);
     xTaskCreate(i2c_test_task, "i2c_test_task_1", 1024 * 2, (void* ) 1, 10, NULL);