导语

翻译自iot in five days 8.2

Example MQTT Topology

MQTT是什么？
MQTT（formerly MQ Telemetry Transport）是一个基于publish-subscribe的通知协议，位于TCP/IP协议之上。它被设计用来连接远端的“small code footprint”或是带宽受限的网络。
publish-subscribe通知模型要求一个消息中间人broker。broker负责散布消息给基于消息主题的感兴趣的客户端。

MQTT有三个级别的服务质量（QoS）:

• QoS 0:broker/client只传送一次消息，没有确认（发送后不管了）
• QoS 1:broker/client至少发送一次消息，会要求确认
• QoS 3:broker/client会通过使用一个四次握手精确传送一次
  查看更多关于MQTT的信息

MQTT API

MQTT的实现位于contiki/apps/mqtt文件夹。它利用了tcp-socket库。当前Contiki中实现的MQTT版本支持QoS 0和1。
　　下面这个函数初始化MQTT引擎，要在其他MQTT函数之前调用。

/*
conn:指向MOTT连接的指针
app_process:指向处理MQTT连接的应用进程
max_segment_size:为MQTT/TCP连接而使用的TCP段大小
*/
mqtt_status_t
mqtt_register(struct mqtt_connection *conn, struct process *app_process,
              char *client_id, mqtt_event_callback_t event_callback,
              uint16_t max_segment_size)

此函数连接到MQTT broker:

mqtt_status_t
mqtt_connect(struct mqtt_connection *conn, char *host, uint16_t port,
             uint16_t keep_alive)

此函数与MQTT broker断开连接

void
mqtt_disconnect(struct mqtt_connection *conn)

此函数subscribe MQTT broker上的一个topic。

/*
mid：指向message id的指针
*/
mqtt_status_t
mqtt_subscribe(struct mqtt_connection *conn, uint16_t *mid, char *topic,
               mqtt_qos_level_t qos_level)

此函数取消subscribe MQTT broker上的一个topic

mqtt_status_t
mqtt_unsubscribe(struct mqtt_connection *conn, uint16_t *mid, char *topic)

此函数publish一个MQTT broker topic

/*retain:如果RETAIN flag设置为1，在一个被client发送给server的PUBLISH包中，server一定要存储应用消息和它的QoS,这样才能被传给未来的订阅名与主题名相匹配的subscribers
*/
mqtt_status_t
mqtt_publish(struct mqtt_connection *conn, uint16_t *mid, char *topic,
             uint8_t *payload, uint32_t payload_size,
             mqtt_qos_level_t qos_level, mqtt_retain_t retain)

下面的函数在连接到MQTT brokers时设置client用户
名和密码。

void
mqtt_set_username_password(struct mqtt_connection *conn, char *username,
                           char *password)

下面的函数设置clients的Last Will topic和信息（payload）。如果Will Flag被设置为1（使用函数）就意味着，如果连接request被接收，一个Will message一定会被存储在server并与网络连接相关联。在网络连接按顺序关闭时，这个Will message一定会被publish。此功能可以在设备与broker断开时获得提醒。

void
mqtt_set_last_will(struct mqtt_connection *conn, char *topic, char *message,
                   mqtt_qos_level_t qos)

下面的函数可以用来维护MQTT连接状态，使用mqtt_connected检查节点是否连接到broker,使用mqtt_ready检查连接是否建立，buffer中还有没有空间来publish。

#define mqtt_connected(conn) \
  ((conn)->state == MQTT_CONN_STATE_CONNECTED_TO_BROKER ? 1 : 0)

#define mqtt_ready(conn) \
  (!(conn)->out_queue_full && mqtt_connected((conn)))

上手：MQTT和mosquitto

#define MQTT_DEMO_BROKER_IP_ADDR "aaaa"::1

mosquitto broker默认绑定主机的IPv4/IPv6地址，如果使用tunslip6脚本的aaaa::1/64地址，它应该匹配MQTT_DEMO_BROKER_IP_ADDR的定义。
本例主要：

• 发布信息到一个MQTT broker
• 订阅一个topic并接收来自MQTT broker的命令。
  注：PUBLISH_TRIGGER也被映射到用户按钮，可以触发一个publish事件。
  　　MQTT客户端配置的数据结构如下：

/**
 * \brief Data structure declaration for the MQTT client configuration
 */
typedef struct mqtt_client_config {
  char org_id[CONFIG_ORG_ID_LEN];//唯一的组织ID
  char type_id[CONFIG_TYPE_ID_LEN];//设备类型
  char auth_token[CONFIG_AUTH_TOKEN_LEN];//授权代表（如果要求）
  char event_type_id[CONFIG_EVENT_TYPE_ID_LEN];//默认事件类型
  char broker_ip[CONFIG_IP_ADDR_STR_LEN];//broker IPv6地址
  char cmd_type[CONFIG_CMD_TYPE_LEN];//默认的命令类型
  clock_time_t pub_interval;//发布间隔周期
  int def_rt_ping_interval;//周期性ping父节点和取RSSI值
  uint16_t broker_port;//broker默认端口，默认是1883
} mqtt_client_config_t;

定义和初始化如下：

static mqtt_client_config_t conf;
static int
init_config()
{
  /* Populate configuration with default values */
  memset(&conf, 0, sizeof(mqtt_client_config_t));

  memcpy(conf.org_id, DEFAULT_ORG_ID, strlen(DEFAULT_ORG_ID));
  memcpy(conf.type_id, DEFAULT_TYPE_ID, strlen(DEFAULT_TYPE_ID));
  memcpy(conf.auth_token, DEFAULT_AUTH_TOKEN, strlen(DEFAULT_AUTH_TOKEN));
  memcpy(conf.event_type_id, DEFAULT_EVENT_TYPE_ID,
         strlen(DEFAULT_EVENT_TYPE_ID));
  memcpy(conf.broker_ip, broker_ip, strlen(broker_ip));
  memcpy(conf.cmd_type, DEFAULT_SUBSCRIBE_CMD_TYPE, 1);

  conf.broker_port = DEFAULT_BROKER_PORT;
  conf.pub_interval = DEFAULT_PUBLISH_INTERVAL;
  conf.def_rt_ping_interval = DEFAULT_RSSI_MEAS_INTERVAL;

  return 1;
}

这个应用例程本身可以被理解为一个有限状态机，尽管看起来复杂但是很直接，mqtt_demo_process开启如下：

PROCESS_THREAD(mqtt_demo_process, ev, data)
{

  PROCESS_BEGIN();

  printf("MQTT Demo Process\n");

  if(init_config() != 1) {//如前所述，不为1则初始化失败
    PROCESS_EXIT();
  }

  update_config();//创建client ID,publish和subscribe topics.初始状态STATE_INIT被设置,publish_periodic_timer事件被安排

  def_rt_rssi = 0x8000000;
  uip_icmp6_echo_reply_callback_add(&echo_reply_notification, echo_reply_handler);//当一个ping事件发生时，注册事件回调
  etimer_set(&echo_request_timer, conf.def_rt_ping_interval);//开启周期ping定时器

  /* Main loop */
  while(1) {

    PROCESS_YIELD();
//通过用户按钮，尝试从STATE_ERROR中恢复
    if(ev == sensors_event && data == PUBLISH_TRIGGER) {
      if(state == STATE_ERROR) {
        connect_attempt = 1;
        state = STATE_REGISTERED;
      }
    }

    if((ev == PROCESS_EVENT_TIMER && data == &publish_periodic_timer) ||
       ev == PROCESS_EVENT_POLL ||
       (ev == sensors_event && data == PUBLISH_TRIGGER)) {
//处理publish_periodic和button事件，这是应用实际开始的地方
      state_machine();
    }

    if(ev == PROCESS_EVENT_TIMER && data == &echo_request_timer) {
//当周期ping定时器结束，ping the parent
      ping_parent();
      etimer_set(&echo_request_timer, conf.def_rt_ping_interval);
    }
  }

  PROCESS_END();
}

当construct_client_id第一次被STATE_INIT调用，state_machine就被调用。

static void
state_machine(void)
{
  switch(state) {
  case STATE_INIT://进入点，注册mqtt连接，进入STATE_REGISTERED事件
    /* If we have just been configured register MQTT connection */
    mqtt_register(&conn, &mqtt_demo_process, client_id, mqtt_event,
                  MAX_TCP_SEGMENT_SIZE);

    /*
     * If we are not using the quickstart service (thus we are an IBM
     * registered device), we need to provide user name and password
     */
    if(strncasecmp(conf.org_id, QUICKSTART, strlen(conf.org_id)) != 0) {
      if(strlen(conf.auth_token) == 0) {
        printf("User name set, but empty auth token\n");
        state = STATE_ERROR;
        break;
      } else {
        mqtt_set_username_password(&conn, "use-token-auth",
                                   conf.auth_token);
      }
    }

    /* _register() will set auto_reconnect. We don't want that. */
    conn.auto_reconnect = 0;
    connect_attempt = 1;

    state = STATE_REGISTERED;
    DBG("Init\n");
    /* Continue */
//企图连接broker，如果节点没有加入网络（没有一个有效的IPv6全局地址）它将稍后尝试。
//如果节点有有效地址那么调用mqtt_connect函数并设置状态为STATE_CONNECTING，
//然后设置publish_periodic_timer为更快的速度
  case STATE_REGISTERED:
    if(uip_ds6_get_global(ADDR_PREFERRED) != NULL) {
      /* Registered and with a public IP. Connect */
      DBG("Registered. Connect attempt %u\n", connect_attempt);
      ping_parent();
      connect_to_broker();
    } else {
      leds_on(STATUS_LED);
      ctimer_set(&ct, NO_NET_LED_DURATION, publish_led_off, NULL);
    }
    etimer_set(&publish_periodic_timer, NET_CONNECT_PERIODIC);
    return;
    break;
//这个事件通知用户连接企图。当MQTT到broker的连接建立后，MQTT_EVENT_CONNECTED
//在mqtt_event回调函数中被触发
  case STATE_CONNECTING:
    leds_on(STATUS_LED);
    ctimer_set(&ct, CONNECTING_LED_DURATION, publish_led_off, NULL);
    /* Not connected yet. Wait */
    DBG("Connecting (%u)\n", connect_attempt);
    break;
//当连接建立后，开始发布，如果不用IBM的quickstart，可以跳过改变状态
//到STATE_PUBLUSHING
  case STATE_CONNECTED:
    /* Don't subscribe unless we are a registered device */
    if(strncasecmp(conf.org_id, QUICKSTART, strlen(conf.org_id)) == 0) {
      DBG("Using 'quickstart': Skipping subscribe\n");
      state = STATE_PUBLISHING;
    }
    /* Continue */
//检查在mqtt_ready中MQTT连接是否OK，然后subscribe和publish
  case STATE_PUBLISHING:
    /* If the timer expired, the connection is stable. */
    if(timer_expired(&connection_life)) {
      /*
       * Intentionally using 0 here instead of 1: We want RECONNECT_ATTEMPTS
       * attempts if we disconnect after a successful connect
       */
      connect_attempt = 0;
    }

    if(mqtt_ready(&conn) && conn.out_buffer_sent) {
      /* Connected. Publish */
      if(state == STATE_CONNECTED) {
        subscribe();
        state = STATE_PUBLISHING;
      } else {
        leds_on(STATUS_LED);
        ctimer_set(&ct, PUBLISH_LED_ON_DURATION, publish_led_off, NULL);
        publish();
      }
      etimer_set(&publish_periodic_timer, conf.pub_interval);

      DBG("Publishing\n");
      /* Return here so we don't end up rescheduling the timer */
      return;
    } else {
      /*
       * Our publish timer fired, but some MQTT packet is already in flight
       * (either not sent at all, or sent but not fully ACKd).
       *
       * This can mean that we have lost connectivity to our broker or that
       * simply there is some network delay. In both cases, we refuse to
       * trigger a new message and we wait for TCP to either ACK the entire
       * packet after retries, or to timeout and notify us.
       */
      DBG("Publishing... (MQTT state=%d, q=%u)\n", conn.state,
          conn.out_queue_full);
    }
    break;
//由MQTT_EVENT_DISCONNECTED触发，处理任意取消连接事件
  case STATE_DISCONNECTED:
    DBG("Disconnected\n");
    if(connect_attempt < RECONNECT_ATTEMPTS ||
       RECONNECT_ATTEMPTS == RETRY_FOREVER) {
      /* Disconnect and backoff */
      clock_time_t interval;
      mqtt_disconnect(&conn);
      connect_attempt++;

      interval = connect_attempt < 3 ? RECONNECT_INTERVAL << connect_attempt :
        RECONNECT_INTERVAL << 3;

      DBG("Disconnected. Attempt %u in %lu ticks\n", connect_attempt, interval);

      etimer_set(&publish_periodic_timer, interval);

      state = STATE_REGISTERED;
      return;
    } else {
      /* Max reconnect attempts reached. Enter error state */
      state = STATE_ERROR;
      DBG("Aborting connection after %u attempts\n", connect_attempt - 1);
    }
    break;
//停止应用，只允许有效配置的值
  case STATE_CONFIG_ERROR:
    /* Idle away. The only way out is a new config */
    printf("Bad configuration.\n");
    return;
//默认事件处理，停止定时器，do nothing
  case STATE_ERROR:
  default:
    leds_on(STATUS_LED);
    /*
     * 'default' should never happen.
     *
     * If we enter here it's because of some error. Stop timers. The only thing
     * that can bring us out is a new config event
     */
    printf("Default case: State=0x%02x\n", state);
    return;
  }

  /* If we didn't return so far, reschedule ourselves */
  etimer_set(&publish_periodic_timer, STATE_MACHINE_PERIODIC);
}

publish函数创造了要被published的字符串数据。下面函数片段中高亮的是最重要的部分，例程周期性地发布下面的信息：

• 设备名
• 一个增长的序列号
• 设备运行时间（以s为单位）
• 片上温度
• 电量
  
  
  　　mqtt_publish更新了MQTT broker的值，发布到特定的pub_topic。默认的topic是construct_pub_topic中完成的iot-2/evt/status/fmt/json。这个topic依照IBM的格式，也可以按其他格式改变。
  　　当从subscribe的topic中接收事件时，MQTT_EVENT_PUBLISH事件被触发，pub_handler被调用。这个例子允许我们打开或关闭红色LED。
  　　例程subscribe的默认topic是iot-2/cmd/+/fmt/json，明确地改变LED状态我们需要publish到iot-2/cmd/leds/fmt/json topic，值1代表打开灯，值0代表关闭。

static void
pub_handler(const char *topic, uint16_t topic_len, const uint8_t *chunk,
            uint16_t chunk_len)
{
  DBG("Pub Handler: topic='%s' (len=%u), chunk_len=%u\n", topic, topic_len,
      chunk_len);

  /* If we don't like the length, ignore */
  if(topic_len != 23 || chunk_len != 1) {
    printf("Incorrect topic or chunk len. Ignored\n");
    return;
  }

  /* If the format != json, ignore */
  if(strncmp(&topic[topic_len - 4], "json", 4) != 0) {
    printf("Incorrect format\n");
  }

  if(strncmp(&topic[10], "leds", 4) == 0) {
    if(chunk[0] == '1') {
      leds_on(LEDS_RED);
    } else if(chunk[0] == '0') {
      leds_off(LEDS_RED);
    }
    return;
  }
}