Skip to main content

API Reference

User functions​

Golain​

golain_err_t golain_init(golain_t golain, golain_config_t config):​

  • Description

    Initialises all the components that have been enabled in esp-idfs menuconfig. MQTT and Device Shadow is initialised by default. The following components are also initialised if enabled:

    • Persistent Logs
    • BLE
    • Device Health

  • Parameters

    • golain : User defined golain_t structure.
    • config : User defined golain_config_t structure.

  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

caution

Remember to initialise the nvs flash before calling this function.

danger

If "Handle wifi" is not enabled in menuconfig, remember to initialise wifi before calling this function.

MQTT​

golain_mqtt_post_data_point(char topic, const void descriptor, void * data, uint32_t length):​

  • Description

    Post device data point to golain. This function encodes the data point too.

  • Parameters

    • topic : The buffer that contains encoded device health protobuffer.
    • descriptor : Device data point fields. (used as <message_name>_fields)
    • data : Pointer to user defined message structure.
    • length : Size of encoded message. ( Can be used as <message_name>_size);

  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

note

Pass DATA_TOPIC(<data point name>) as the topic parameter. The data point name is defined on the golain platform by the user.

golain_mqtt_post_shadow(golain_t* golain):​

  • Description

    Post device shadow to the platform

  • Parameters

  • golain : User defined golain_t structure. insert link

  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

golain_err_t golain_mqtt_post_user_assoc(golain_t, uint8_t buff, uint8_t len):​

  • Description

    Post device data point to platform in order to kick ass and take names.

  • Parameters

    • topic : The buffer that contains encoded device health protobuffer.
    • descriptor : Device data point fields. (used as <message_name>_fields)
    • data : Pointer to user defined message structure.
    • length : Size of encoded message. ( Can be used as <message_name>_size);

  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

WiFi​

golain_err_t golain_hal_wifi_init():​

  • Description Initialises the WiFi

  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

golain_err_t golain_hal_wifi_disconnect(void):​

  • Description Disconnect the device from WiFi

  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

Device Shadow​

golain_err_t golain_shadow_init(golain_t*);​

  • Description Initialises the device shadow service. It also checks for previously written shadows in the NVS.
  • Parameters
  • golain : User defined golain_t structure. insert link
  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

golain_err_t golain_shadow_update(golain_t*);​

  • Description Updates the NVS as well as the platform with the device shadow.
  • Parameters
  • golain : User defined golain_t structure. insert link
  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

Device Health​

golain_err_t golain_device_health_encode_message(uint8_t buffer, size_t buffer_size, size_t message_length):​

  • Description Encodes device health protobuf into a buffer of the user's choice.
  • Parameters
    • buffer : The buffer that you would want to fill with encoded device health protobuffer.
    • buffer_size : Size of the above buffer.
    • message_length : Size of the device health protobuffer.
  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

golain_err_t golain_device_health_decode_message(uint8_t *buffer, size_t message_length):​

  • Description Decodes device health protobuf from a buffer of the user's choice.
  • Parameters
    • buffer : The buffer that contains encoded device health protobuffer.
    • message_length : Size of the device health protobuffer.
  • Return Returns GOLAIN_OK on success, golain_err_t error value on error.

Golain Nanopb encoding functions​

golain_pb_decode_string(pb_istream_t stream, const pb_field_t field, void **arg):​

  • Description Callback for decoding a string.
  • Parameters
    • stream : Output stream for the protobuffer.
    • field : Protobuffer fields.
    • arg : Arguements where decoded data is stored.
  • Return Returns 1 on success, 0 on error.

golain_pb_encode_string(pb_ostream_t stream, const pb_field_t field, void const arg) :​

  • Description Callback for encoding a string.
  • Parameters
    • stream : Output stream for the protobuffer.
    • field : Protobuffer fields.
    • arg : Structures that are to be encoded.
  • Return Returns 1 on success, 0 on error.

User Structs​

golain_config_t:​

  • User defined callbacks
    • on_connect
    • on_disconnect
    • on_shadow_update_from_mqtt : The function that is called when the device shadow is updated from the platform
    • on_data_publish
  • Device Shadow requirements
    • shadow_struct : Pointer to the user defined device shadow structure. (Should look like .shadow_struct = &shadow);
    • shadow_fields : pb_msgdesc_t for the device shadow. (Shadow_fields)
    • shadow_size : Maximum size of the encoded shadow buffer.
  • MQTT Certificates
    • device_cert : Should be assigned with the device_cert.pem binary.
    • device_pvt_key : Should be assigned with the device_private_key.pem binary.
    • root_ca_cert_start : Should be assigned with the root_ca_cert.pem binary
    • root_ca_cert_len : Length of the root_ca_cert.
  • BLE
    • on_shadow_update_from_ble : Called when shadow is updated from BLE.
  • OTA
    • on_ota_payload_received : Called when the device receives an OTA payload.

golain_t​

  • config : The user defined golain_config_t structure. Defined by golain_init() function.
  • mqtt_is_connected : true when the device is connected to golain via MQTT, 0 when disconnected.

User MACROS​

  • DATA_TOPIC(x) : Adds x to GOLAIN_DATA_TOPIC. Use this when posting your device's data point.

  • GOLAIN_LOG_I(tag, format, ...) : Works like ESP_LOGI. However, when persistent logs is enabled, the log is written to NVS too.

  • GOLAIN_LOG_W(tag, format, ...) : Works like ESP_LOGW. However, when persistent logs is enabled, the log is written to NVS too.
  • GOLAIN_LOG_E(tag, format, ...) : Works like ESP_LOGE. However, when persistent logs is enabled, the log is written to NVS too.
  • GOLAIN_LOG_D(tag, format, ...) : Works like ESP_LOGD.