nrf_cloud.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef NRF_CLOUD_H__
#define NRF_CLOUD_H__
 
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/net/mqtt.h>
#if defined(CONFIG_MODEM_INFO)
#include <modem/modem_info.h>
#endif
#include <net/nrf_cloud_defs.h>
#include <dfu/dfu_target_full_modem.h>
#if defined(CONFIG_NRF_MODEM)
#include <nrf_modem_gnss.h>
#endif
#include <net/nrf_cloud_os.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define NCT_MSG_ID_USE_NEXT_INCREMENT     0
#define NCT_MSG_ID_CC_SUB               100
#define NCT_MSG_ID_DC_SUB               101
#define NCT_MSG_ID_FOTA_SUB             103
#define NCT_MSG_ID_CC_UNSUB             150
#define NCT_MSG_ID_DC_UNSUB             151
#define NCT_MSG_ID_FOTA_UNSUB           153
#define NCT_MSG_ID_STATE_REQUEST        200
#define NCT_MSG_ID_FOTA_REQUEST         201
#define NCT_MSG_ID_FOTA_BLE_REQUEST     202
#define NCT_MSG_ID_STATE_REPORT         300
#define NCT_MSG_ID_PAIR_STATUS_REPORT   301
#define NCT_MSG_ID_FOTA_REPORT          302
#define NCT_MSG_ID_FOTA_BLE_REPORT      303
#define NCT_MSG_ID_INCREMENT_BEGIN     1000
#define NCT_MSG_ID_INCREMENT_END       9999
#define NCT_MSG_ID_USER_TAG_BEGIN      (NCT_MSG_ID_INCREMENT_END + 1)
#define NCT_MSG_ID_USER_TAG_END        0xFFFF /* MQTT message IDs are uint16_t */
 
#define IS_VALID_USER_TAG(tag) ((tag >= NCT_MSG_ID_USER_TAG_BEGIN) && \
                                (tag <= NCT_MSG_ID_USER_TAG_END))
 
#define NRF_CLOUD_JWT_VALID_TIME_S_MAX          (7 * 24 * 60 * 60)
#define NRF_CLOUD_JWT_VALID_TIME_S_DEF          (10 * 60)
 
#define NRF_CLOUD_NO_TIMESTAMP 0
 
enum nrf_cloud_evt_type {
        NRF_CLOUD_EVT_TRANSPORT_CONNECTED = 0x1,
        NRF_CLOUD_EVT_TRANSPORT_CONNECTING,
        NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST,
        NRF_CLOUD_EVT_USER_ASSOCIATED,
        NRF_CLOUD_EVT_READY,
        NRF_CLOUD_EVT_RX_DATA_GENERAL,
        NRF_CLOUD_EVT_RX_DATA_DISCON,
        NRF_CLOUD_EVT_RX_DATA_LOCATION,
        NRF_CLOUD_EVT_RX_DATA_SHADOW,
        NRF_CLOUD_EVT_PINGRESP,
        NRF_CLOUD_EVT_SENSOR_DATA_ACK,
        NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED,
        NRF_CLOUD_EVT_FOTA_START,
        NRF_CLOUD_EVT_FOTA_DONE,
        NRF_CLOUD_EVT_FOTA_ERROR,
        NRF_CLOUD_EVT_TRANSPORT_CONNECT_ERROR,
        NRF_CLOUD_EVT_FOTA_JOB_AVAILABLE,
        NRF_CLOUD_EVT_ERROR = 0xFF
};
 
enum nrf_cloud_error_status {
        NRF_CLOUD_ERR_STATUS_NONE = 0,
 
        NRF_CLOUD_ERR_STATUS_MQTT_CONN_FAIL,
        NRF_CLOUD_ERR_STATUS_MQTT_CONN_BAD_PROT_VER,
        NRF_CLOUD_ERR_STATUS_MQTT_CONN_ID_REJECTED,
        NRF_CLOUD_ERR_STATUS_MQTT_CONN_SERVER_UNAVAIL,
        NRF_CLOUD_ERR_STATUS_MQTT_CONN_BAD_USR_PWD,
        NRF_CLOUD_ERR_STATUS_MQTT_CONN_NOT_AUTH,
        NRF_CLOUD_ERR_STATUS_MQTT_SUB_FAIL,
        NRF_CLOUD_ERR_STATUS_AGNSS_PROC,
        NRF_CLOUD_ERR_STATUS_PGPS_PROC,
};
 
enum nrf_cloud_disconnect_status {
        NRF_CLOUD_DISCONNECT_USER_REQUEST,
        NRF_CLOUD_DISCONNECT_CLOSED_BY_REMOTE,
        NRF_CLOUD_DISCONNECT_INVALID_REQUEST,
        NRF_CLOUD_DISCONNECT_MISC,
};
 
enum nrf_cloud_connect_result {
        NRF_CLOUD_CONNECT_RES_SUCCESS = 0,
        NRF_CLOUD_CONNECT_RES_ERR_NOT_INITD = -1,
        NRF_CLOUD_CONNECT_RES_ERR_NETWORK = -3,
        NRF_CLOUD_CONNECT_RES_ERR_BACKEND = -4,
        NRF_CLOUD_CONNECT_RES_ERR_MISC = -5,
        NRF_CLOUD_CONNECT_RES_ERR_NO_MEM = -6,
        NRF_CLOUD_CONNECT_RES_ERR_PRV_KEY = -7,
        NRF_CLOUD_CONNECT_RES_ERR_CERT = -8,
        NRF_CLOUD_CONNECT_RES_ERR_CERT_MISC = -9,
        NRF_CLOUD_CONNECT_RES_ERR_TIMEOUT_NO_DATA = -10,
        NRF_CLOUD_CONNECT_RES_ERR_ALREADY_CONNECTED = -11,
};
 
enum nrf_cloud_error {
        NRF_CLOUD_ERROR_UNKNOWN                 = -1,
        NRF_CLOUD_ERROR_NONE                    = 0,
        /* nRF Cloud API defined error codes below */
        NRF_CLOUD_ERROR_BAD_REQUEST             = 40000,
        NRF_CLOUD_ERROR_INVALID_CERT            = 40001,
        NRF_CLOUD_ERROR_DISSOCIATE              = 40002,
        NRF_CLOUD_ERROR_ACCESS_DENIED           = 40100,
        NRF_CLOUD_ERROR_DEV_ID_IN_USE           = 40101,
        NRF_CLOUD_ERROR_INVALID_OWNER_CODE      = 40102,
        NRF_CLOUD_ERROR_DEV_NOT_ASSOCIATED      = 40103,
        NRF_CLOUD_ERROR_DATA_NOT_FOUND          = 40410,
        NRF_CLOUD_ERROR_NRF_DEV_NOT_FOUND       = 40411,
        NRF_CLOUD_ERROR_NO_DEV_NOT_PROV         = 40412,
        NRF_CLOUD_ERROR_NO_DEV_DISSOCIATE       = 40413,
        NRF_CLOUD_ERROR_NO_DEV_DELETE           = 40414,
        /* Item was not found. No error occurred, the requested item simply does not exist */
        NRF_CLOUD_ERROR_NOT_FOUND_NO_ERROR      = 40499,
        NRF_CLOUD_ERROR_BAD_RANGE               = 41600,
        NRF_CLOUD_ERROR_VALIDATION              = 42200,
        NRF_CLOUD_ERROR_INTERNAL_SERVER         = 50010,
};
 
enum nrf_cloud_sensor {
        NRF_CLOUD_SENSOR_GNSS,
        NRF_CLOUD_SENSOR_FLIP,
        NRF_CLOUD_SENSOR_BUTTON,
        NRF_CLOUD_SENSOR_TEMP,
        NRF_CLOUD_SENSOR_HUMID,
        NRF_CLOUD_SENSOR_AIR_PRESS,
        NRF_CLOUD_SENSOR_AIR_QUAL,
        NRF_CLOUD_LTE_LINK_RSRP,
        NRF_CLOUD_LOG,
        NRF_CLOUD_DICTIONARY_LOG,
        NRF_CLOUD_DEVICE_INFO,
        NRF_CLOUD_SENSOR_LIGHT,
};
 
enum nrf_cloud_topic_type {
        NRF_CLOUD_TOPIC_STATE = 0x1,
        NRF_CLOUD_TOPIC_MESSAGE,
        NRF_CLOUD_TOPIC_BULK,
        NRF_CLOUD_TOPIC_BIN,
#if defined(CONFIG_NRF_CLOUD_MQTT_SHADOW_TRANSFORMS)
        NRF_CLOUD_TOPIC_STATE_TF,
#endif
};
 
enum nrf_cloud_fota_status {
        NRF_CLOUD_FOTA_QUEUED = 0,
        NRF_CLOUD_FOTA_IN_PROGRESS = 1,
        NRF_CLOUD_FOTA_FAILED = 2,
        NRF_CLOUD_FOTA_SUCCEEDED = 3,
        NRF_CLOUD_FOTA_TIMED_OUT = 4,
        NRF_CLOUD_FOTA_CANCELED = 5,
        NRF_CLOUD_FOTA_REJECTED = 6,
        NRF_CLOUD_FOTA_DOWNLOADING = 7,
};
 
enum nrf_cloud_fota_type {
        NRF_CLOUD_FOTA_TYPE__FIRST = 0,
 
        NRF_CLOUD_FOTA_APPLICATION = NRF_CLOUD_FOTA_TYPE__FIRST,
        NRF_CLOUD_FOTA_MODEM_DELTA = 1,
        NRF_CLOUD_FOTA_BOOTLOADER = 2,
 
        /* Types not handled by this library:
         * NRF_CLOUD_FOTA_BLE_BOOT = 3,
         * NRF_CLOUD_FOTA_BLE_SOFTDEVICE = 4,
         */
 
        NRF_CLOUD_FOTA_MODEM_FULL = 5,
        NRF_CLOUD_FOTA_SMP = 6,
 
        NRF_CLOUD_FOTA_TYPE__INVALID
};
 
#define NRF_CLOUD_FOTA_JOB_ID_SIZE (32 + 4 + 1)
 
struct nrf_cloud_fota_job_info {
        enum nrf_cloud_fota_type type;
        char *id;
        char *host;
        char *path;
        int file_size;
};
 
enum nrf_cloud_fota_validate_status {
        NRF_CLOUD_FOTA_VALIDATE_NONE = 0,
        NRF_CLOUD_FOTA_VALIDATE_PENDING,
        NRF_CLOUD_FOTA_VALIDATE_PASS,
        NRF_CLOUD_FOTA_VALIDATE_FAIL,
        NRF_CLOUD_FOTA_VALIDATE_UNKNOWN,
        NRF_CLOUD_FOTA_VALIDATE_DONE,
        NRF_CLOUD_FOTA_VALIDATE_ERROR,
};
 
enum nrf_cloud_fota_bootloader_status_flags {
        NRF_CLOUD_FOTA_BL_STATUS_CLEAR          = 0,
        NRF_CLOUD_FOTA_BL_STATUS_S0_FLAG_SET    = (1 << 0),
        NRF_CLOUD_FOTA_BL_STATUS_S0_WAS_ACTIVE  = (1 << 1),
        NRF_CLOUD_FOTA_BL_STATUS_REBOOTED       = (1 << 2),
};
 
struct nrf_cloud_settings_fota_job {
        enum nrf_cloud_fota_validate_status validate;
        enum nrf_cloud_fota_type type;
        char id[NRF_CLOUD_FOTA_JOB_ID_SIZE];
        enum nrf_cloud_fota_bootloader_status_flags bl_flags;
};
 
struct nrf_cloud_data {
        uint32_t len;
        const void *ptr;
};
 
struct nrf_cloud_topic {
        uint32_t len;
        const void *ptr;
};
 
struct nrf_cloud_sensor_data {
        enum nrf_cloud_sensor type;
        struct nrf_cloud_data data;
        uint16_t tag;
        int64_t ts_ms;
};
 
struct nrf_cloud_evt {
        enum nrf_cloud_evt_type type;
        uint32_t status;
        struct nrf_cloud_data data;
        struct nrf_cloud_topic topic;
        struct nrf_cloud_obj_shadow_data *shadow;
};
 
struct nrf_cloud_tx_data {
        struct nrf_cloud_obj *obj;
        struct nrf_cloud_data data;
 
        enum nrf_cloud_topic_type topic_type;
        enum mqtt_qos qos;
        uint32_t id;
};
 
struct nrf_cloud_svc_info_fota {
        uint8_t bootloader:1;
        uint8_t modem:1;
        uint8_t application:1;
        uint8_t modem_full:1;
        uint8_t smp:1;
 
        uint8_t _rsvd:3;
};
 
struct nrf_cloud_svc_info_ui {
        /* Items with UI support on nRF Cloud */
        uint8_t temperature:1;
        uint8_t gnss:1;
        uint8_t flip:1;
        uint8_t humidity:1;
        uint8_t air_pressure:1;
        uint8_t rsrp:1;
        uint8_t log:1;
        uint8_t dictionary_log:1;
        uint8_t air_quality:1;
 
        /* Items without UI support on nRF Cloud */
        uint8_t light_sensor:1;
        uint8_t button:1;
 
        uint8_t _rsvd:5;
};
 
enum nrf_cloud_shadow_info {
        NRF_CLOUD_INFO_NO_CHANGE = 0,
        NRF_CLOUD_INFO_SET = 1,
        NRF_CLOUD_INFO_CLEAR = 2,
};
 
struct nrf_cloud_modem_info {
        enum nrf_cloud_shadow_info device;
        enum nrf_cloud_shadow_info network;
        enum nrf_cloud_shadow_info sim;
 
#if defined(CONFIG_MODEM_INFO)
        const struct modem_param_info *mpi;
#endif
 
        const char *application_version;
};
 
struct nrf_cloud_svc_info {
        struct nrf_cloud_svc_info_fota *fota;
 
        struct nrf_cloud_svc_info_ui *ui;
};
 
struct nrf_cloud_device_status {
        struct nrf_cloud_modem_info *modem;
        struct nrf_cloud_svc_info *svc;
        enum nrf_cloud_shadow_info conn_inf;
};
 
enum nrf_cloud_gnss_type {
        NRF_CLOUD_GNSS_TYPE_INVALID,
        NRF_CLOUD_GNSS_TYPE_PVT,
        NRF_CLOUD_GNSS_TYPE_NMEA,
        NRF_CLOUD_GNSS_TYPE_MODEM_PVT,
        NRF_CLOUD_GNSS_TYPE_MODEM_NMEA,
};
 
struct nrf_cloud_gnss_pvt {
        double lat;
        double lon;
        float accuracy;
 
        float alt;
        float speed;
        float heading;
 
        uint8_t has_alt:1;
        uint8_t has_speed:1;
        uint8_t has_heading:1;
 
        uint8_t _rsvd:5;
};
 
struct nrf_cloud_credentials_status {
        /* Configured sec_tag for nRF Cloud */
        uint32_t sec_tag;
        size_t ca_size;
 
        /* Flags to indicate if the specified credentials exist */
        uint8_t ca:1;
        uint8_t ca_coap:1;
        uint8_t ca_aws:1;
        uint8_t client_cert:1;
        uint8_t prv_key:1;
};
 
#if !defined(CONFIG_NRF_MODEM)
#define NRF_MODEM_GNSS_NMEA_MAX_LEN 83
#endif
struct nrf_cloud_gnss_nmea {
        const char *sentence;
};
 
struct nrf_cloud_gnss_data {
        enum nrf_cloud_gnss_type type;
        int64_t ts_ms;
        union {
                struct nrf_cloud_gnss_pvt pvt;
                struct nrf_cloud_gnss_nmea nmea;
#if defined(CONFIG_NRF_MODEM)
                struct nrf_modem_gnss_nmea_data_frame *mdm_nmea;
                struct nrf_modem_gnss_pvt_data_frame *mdm_pvt;
#endif
        };
};
 
#ifdef CONFIG_NRF_CLOUD_GATEWAY
struct nrf_cloud_gw_data {
        struct nrf_cloud_data data;
        uint16_t id;
};
#endif
 
struct nrf_cloud_ctrl_data {
        bool alerts_enabled;
        int log_level;
};
 
typedef void (*nrf_cloud_event_handler_t)(const struct nrf_cloud_evt *evt);
 
struct nrf_cloud_init_param {
        nrf_cloud_event_handler_t event_handler;
        char *client_id;
        struct dfu_target_fmfu_fdev *fmfu_dev_inf;
        struct nrf_cloud_os_mem_hooks *hooks;
        const char *application_version;
 
        void *smp_reset_cb;
};
 
int nrf_cloud_init(const struct nrf_cloud_init_param *param);
 
int nrf_cloud_uninit(void);
 
int nrf_cloud_print_details(void);
 
int nrf_cloud_print_cloud_details(void);
 
int nrf_cloud_get_imei(char *buf, size_t buf_sz);
 
int nrf_cloud_get_uuid(char *buf, size_t buf_sz);
 
int nrf_cloud_get_modem_fw(char *buf, size_t buf_sz);
 
int nrf_cloud_connect(void);
 
int nrf_cloud_sensor_data_send(const struct nrf_cloud_sensor_data *param);
 
int nrf_cloud_shadow_device_status_update(const struct nrf_cloud_device_status * const dev_status);
 
int nrf_cloud_sensor_data_stream(const struct nrf_cloud_sensor_data *param);
 
int nrf_cloud_send(const struct nrf_cloud_tx_data *msg);
 
int nrf_cloud_obj_shadow_update(struct nrf_cloud_obj *const shadow_obj);
 
int nrf_cloud_shadow_transform_request(char const *const transform, const size_t max_response_len);
 
int nrf_cloud_disconnect(void);
 
int nrf_cloud_process(void);
 
int nrf_cloud_modem_fota_completed(const bool fota_success);
 
int nrf_cloud_client_id_get(char *id_buf, size_t id_buf_sz);
 
int nrf_cloud_client_id_runtime_set(const char *const client_id);
 
int nrf_cloud_tenant_id_get(char *id_buf, size_t id_len);
 
int nrf_cloud_jwt_generate(uint32_t time_valid_s, char * const jwt_buf, size_t jwt_buf_sz);
 
int nrf_cloud_pending_fota_job_process(struct nrf_cloud_settings_fota_job * const job,
                                       bool * const reboot_required);
 
int nrf_cloud_bootloader_fota_slot_set(struct nrf_cloud_settings_fota_job * const job);
 
int nrf_cloud_fota_pending_job_type_get(enum nrf_cloud_fota_type * const pending_fota_type);
 
int nrf_cloud_fota_pending_job_validate(enum nrf_cloud_fota_type * const fota_type_out);
 
int nrf_cloud_fota_fmfu_dev_set(const struct dfu_target_fmfu_fdev *const fmfu_dev_inf);
 
int nrf_cloud_fota_fmfu_apply(void);
 
bool nrf_cloud_fota_is_type_modem(const enum nrf_cloud_fota_type type);
 
bool nrf_cloud_fota_is_type_enabled(const enum nrf_cloud_fota_type type);
 
int nrf_cloud_fota_job_start(void);
 
int nrf_cloud_fota_smp_client_init(const void *smp_reset_cb);
 
int nrf_cloud_fota_smp_install(void);
 
int nrf_cloud_fota_smp_version_read(void);
 
int nrf_cloud_fota_smp_version_get(char **smp_ver_out);
 
int nrf_cloud_credentials_check(struct nrf_cloud_credentials_status *const cs);
 
int nrf_cloud_credentials_configured_check(void);
 
void nrf_cloud_sec_tag_set(const sec_tag_t sec_tag);
 
sec_tag_t nrf_cloud_sec_tag_get(void);
 
void nrf_cloud_sec_tag_coap_jwt_set(const sec_tag_t sec_tag);
 
sec_tag_t nrf_cloud_sec_tag_coap_jwt_get(void);
 
#ifdef __cplusplus
}
#endif
 
#endif /* NRF_CLOUD_H__ */