Embedded APIs

Configuration and Management

ArrayentConfigure

Configures the Arrayent Connect Agent.

Synopsis

arrayent_return_e ArrayentConfigure(arrayent_config_t *config)

Usage

ArrayentConfigure sets all of your device’s Arrayent attributes before starting the ACA. Before calling ArrayentConfigure you should call ArrayentSetConfigDefaults. If ArrayentConfigure is called after ArrayentInit, ArrayentConfigure will automatically call ArrayentReset if the reconfiguration structure was accepted. In the unlikely case that reconfiguration is successful but resetting is not, the host application must retry resetting the ACA until it succeeds before attempting any communication through the ACA. If you call ArrayentConfigure() with valid configuration fields and then call it again with invalid fields, ArrayentConfigure()returns an error but the ACA continues to use the prior (good) configuration. ArrayentConfigure does not check the validity of the provided DNS names. Therefore ArrayentConfigure may returnARRAYENT_SUCCESS even if these values are empty, wrong names or out of range values. Errors may be returned when callingArrayentInit and these values are used to connect to the cloud.

Postconditions

• config.aca_stack_size is set to a fixed value determined by the ACA.

Parameters

Name	Data Type	Description
config	arrayent_config_t*	Structure fully populated with Arrayent configuration arguments.

Response

Data Type	Description
arrayent_return_e	Indicates whether or not the configuration was accepted.

ArrayentSetConfigDefaults

Populates an ACA configuration structure (arrayent_config_t) with default settings.

Synopsis

arrayent_return_e ArrayentSetConfigDefaults(arrayent_config_t *config)

Usage

In future releases of the ACA, Arrayent may need to add extra optional configuration parameters to the Arrayent configuration structarrayent_config_t. This runs the risk of breaking your application, because when your application upgrades to a new version of the ACA, the new configuration parameters would be missing. ArrayentSetConfigDefaults solves this problem by providing a mechanism for automatically populating those new optional configuration parameters with default values. This ensures that your application can safely upgrade to new versions of the ACA. Call this function before you call ArrayentConfigure, passing an arrayent_config_t as an argument. Once complete, populate the struct with values for all of the required members. Last, pass that same struct as an argument to ArrayentConfigure.
Note Note that your application must still set most fields in the ACA configuration structure after having called this function on it. This function only populates settings for optional features of ACA.
Warning Do not call this function after calling ArrayentConfigure as it will override some of the configuration settings you made with ArrayentConfigure and your application will not work.

Postconditions

• config.load_balancer_udp_port is set to 80.
• config.load_balancer_tcp_port is set to 80.
• config.aca_thread_priority is set to 7.
• config.aca_stack_size is set to a fixed value determined by the ACA.

Parameters

Name	Data Type	Description
config	arrayent_config_t*	Output: ACA configuration structure to populate.

Response

Data Type	Description
arrayent_return_e	Indicates whether the ACA configuration structure was successfully populated with default settings.

ArrayentInit

Initializes the ACA.

Synopsis

arrayent_return_e ArrayentInit()

Usage

ArrayentInit starts the ACA and prepares the ACA for communication with the Arrayent Cloud. By default the ACA uses UDP to connect to the Arrayent Cloud. If UDP fails, the ACA attempts to connect to the cloud using TCP. UseArrayentNetStatus to determine if the ACA is using UDP or TCP.
Warning The host application should only call ArrayentInit once. In other words, after the host application calls ArrayentInit and the ACA connects to the Arrayent Cloud, the host application should never call ArrayentInit again. Calling it multiple times will result in undefined behavior.

Preconditions

The host application must successfully configure every Arrayent property using ArrayentConfigure. The Arrayent thread may hang if this function is called prior to configuring all Arrayent properties. The host application must seed the machine’s random number generator with srand before calling this function.

Response

Data Type	Description
arrayent_return_e	Indicates if initialization was completed successfully.

ArrayentNetStatus

Checks connection to Arrayent Cloud.
Warning ArrayentNetStatus must only be called from one thread. Do not call this function from more than one thread. Calling it from more than one thread results in undefined behavior.

Synopsis

arrayent_return_e ArrayentNetStatus(arrayent_net_status_t *status)

Usage

ArrayentNetStatus returns a bit field indicating the network status of the ACA. The bit field is in the format ofarrayent_net_status_t.
Warning For ACA versions 1.5.1 and below, ArrayentNetStatus should never be called from different threads. In ACA versions 1.5.2 and above it is safe to call ArrayentNetStatus from different threads.
Warning For ACA versions 1.5.1 and below, ArrayentNetStatus is not thread safe in conjunction with ArrayentSetProperty,ArrayentSetMultiAttribute, or ArrayentSendData. Calling ArrayentNetStatus while simultaneously callingArrayentSetProperty, ArrayentSetMultiAttribute, or ArrayentSendData can result in undefined behavior. In ACA versions 1.5.2 and above this is no longer an issue.

Parameters

Name	Data Type	Description
status	arrayent_net_status_t*	Pointer to the status structure to be updated. See arrayent_net_status_t.

Response

Data Type	Description
arrayent_return_e	Indicates if the status was updated.

ArrayentReset

Resets the ACA.

Synopsis

arrayent_return_e ArrayentReset()

Usage

This function forces the ACA’s state machine to reset and log back in to the Arrayent Cloud. It may be called at any time after initialization is complete. Be sure to poll ArrayentNetStatus for cloud connection before attempting Arrayent communication after a reset. As of ACA version 1.5.2 the ACA drops all messages that it receives from the cloud during the initialization process. If, after 15 minutes of polling, the ACA remains unconnected, you may call ArrayentResetonce.

Postconditions

Failure: ACA times out if function takes more than 5 seconds to complete.

Response

Data Type	Description
arrayent_return_e	Indicates if the reset was accepted.

ArrayentDeregister

Removes a device from a user account. This function name was changed from ArrayentFactoryResetDevice to ArrayentDeregister in ACA v1.6.

Synopsis

arrayent_return_e ArrayentDeregister()

Usage

ArrayentDeregister sends a special command to the cloud to disassociate the device from the user account which currently owns it.

Response

Data Type	Description
arrayent_return_e	Indicates if the device was successfully removed from the user account.

ArrayentGetTime

Retrieves the current time from the Arrayent Cloud.

Synopsis

arrayent_return_e ArrayentGetTime(arrayent_timestamp_t *timestamp, int16_t timezone)

Usage

This function blocks for up to three seconds while it waits for a response from the cloud.
Warning When Arrayent returns the timestamp, the month value will be 0-based (valid values: 0 to 11). The day value will be 1-based (valid values: 1 to 31).
Warning Setting timezone to a GMT offset is supposed to return a timestamp formatted for that timezone, but this feature is not currently implemented. For the time being, always set timezone to 0.

Parameters

Name	Data Type	Description
timestamp	arrayent_timestamp_t*	Pointer to structure to fill with current time. The month value will be 0-based. The day value will be 0-based. The hour value will be 0 to 23. Minute and second will be 0 to 59.
timezone	int16_t	Set this to 0. Timezone offset is not currently supported.

Response

Data Type	Description
arrayent_return_e	Indicates if the timestamp was received. If notARRAYENT_SUCCESS, *timestamp does NOT contain a valid timestamp.

ArrayentGetVersion

Gets the ACA version.

Synopsis

constchar* ArrayentGetVersion(void)

Parameters

None.

Response

Data Type	Description
char*	The ACA version in a.b.c.d format, where a isACA_VERSION_MAJOR, b is ACA_VERSION_MINOR, c isACA_VERSION_REVISION, and d isACA_VERSION_SUBREVISION.

ArrayentHello

Checks connection to the ACA.

Synopsis

arrayent_return_e ArrayentHello()

Usage

ArrayentHello sends a hello message to the ACA. The return value of the function indicates if the ACA is able to communicate correctly.

Postconditions

Failure: ACA times out if function takes more than 5 seconds to complete.

Response

Data Type	Description
arrayent_return_e	Indicates if the hello was verified.

ArrayentSleep

Instructs the ACA to sleep.

Synopsis

arrayent_return_e ArrayentSleep(arrayent_sleep_level_e sleep_level)

Usage

ArrayentSleep instructs the ACA to go to sleep until ArrayentWake is called.

Postconditions

ACA times out if function takes more than 5 seconds to complete.

Parameters

Name	Data Type	Description
sleep_level	arrayent_sleep_level_e	Sets the exact sleep behavior.“ARRAYENT_MIN_SLEEP_LEVEL“: Arrayent threads are paused, and dynamic networking resources are torn down. On wake, networking resources are recreated and the Arrayent state machines resume with whatever state they were in prior to being put to sleep. UseARRAYENT_MIN_SLEEP_LEVEL when your application expects to sleep for less than a minute or so. If you aren’t sure how long your application will sleep for, useARRAYENT_MIN_SLEEP_LEVEL. Waking up from this sleep level requires the least amount of IP traffic (and therefore the least amount of power) of all.“ARRAYENT_DEEPSLEEP“: Same asARRAYENT_MIN_SLEEP_LEVEL. Future versions may differentiate between the two.

Response

Data Type	Description
arrayent_return_e	Indicates whether or not the ACA was successfully suspended.

ArrayentWake

Wakes the ACA.

Synopsis

arrayent_return_eArrayentWake()

Usage

ArrayentWake brings the ACA out of sleep, causing it to reestablish its connection with the Arrayent Cloud. Exact behavior depends on what arrayent_sleep_level_e argument was passed when ArrayentSleep was called. Applications should poll ArrayentNetStatus for success after this function has been called and before sending property updates to the cloud.

Response

Data Type	Description
arrayent_return_e	Indicates whether or not the ACA is now in the process of resuming.

Data flow

ArrayentRecvData

Receives a raw data message. “Raw data” means data that is structured in a format that is not natively supported by the Arrayent Cloud.

Synopsis

arrayent_return_e ArrayentRecvData(uint8_t* data, uint16_t* data_type, uint16_t* len, uint32_t timeout)

Usage

This function is blocking; it will not return until either a data message has been received from the cloud or the time specified in the timeout argument has elapsed.

Preconditions

This function will not work unless your organization has coordinated with Arrayent to implement a parser in the Arrayent Cloud that converts your raw data to Arrayent key-value pair format.

Postconditions

When ACA returns ARRAYENT_SUCCESS

data contains the message payload. The message payload will be structured in the custom format that you have specified to Arrayent. data_type contains the Arrayent data type enumerator of the message payload. len contains the length of the data payload in bytes.

When ACA returns ARRAYENT_MSG_TOO_BIG

Problem: Length of data buffer was not large enough for the received data. Possible Solution: Increase the size of your data buffer. Possbible Solution: Always set len to the size of your buffer (data) before every call to ArrayentRecvData. Example: You may see this return code if you call this function multiple times without resetting len to the size of your buffer before every call. Consider the following scenario:

1. Host calls ArrayentRecvData(&data,&data_type,&length,UINT32_MAX);, where data is a buffer 20 bytes long andlength is sizeof(data).
2. ACA receives a 10 byte message from the cloud, stores it in data, and sets length to 10 (the size of the message).
3. Host calls ArrayentRecvData(&data,&data_type,&length,UINT32_MAX); again. This time length equals 10 because that is what the ACA set it to in the last step.
4. ACA receives another message, this time 15 bytes long.
5. ACA returns ARRAYENT_MSG_TOO_BIG because the received message is 15 bytes long, but length is 10.

Parameters

Name	Data Type	Description
data	uint8_t*	Where to place the received raw data message. This buffer is not touched if no message is received.
data_type	uint16_t*	The Arrayent data type enumerator of the received raw data message.
len	uint16_t*	Input: the length of the receive buffer. This buffer should be at least the length of the longest expected message. Output: if a data message is received,len is set to the length of the raw data message in bytes. In the event of an insufficiently sized receive buffer, len will not equal the length of the received data. If no data message is received, len is set to 0.
timeout	uint32_t	Timeout for the receive operation to complete, in milliseconds. Set to 0 to indicate no wait.

Return Value

Data Type	Description
arrayent_return_e	Indicates if a data message was received from the cloud.

ArrayentRecvMultiAttribute

Receive a multi-attribute message from the ACA.

Synopsis

arrayent_return_e ArrayentRecvMultiAttribute(uint8_t *data, uint16_t *len, uint32_t timeout)

Usage

This function listens for a multi-attribute message from the Arrayent Cloud. The function is blocking; it will not return until either a multi-attribute message has been received from the server or the timeout argument has elapsed. ACA support for unsigned integer data types was introduced in ACA 1.5. See Data Types Reference for more information about data types.

Preconditions

In order to use this function your host application must have set device_can_multi_attribute of arrayent_config_t to 1 before it called ArrayentConfigure. An enumerated alias has been defined in the Arrayent Cloud for every attribute that is being updated.

Postconditions

Success:data contains a message in the multi-attribute payload format. See Multi-Attribute Payload Format len contains the length of data in bytes. Failure: ACA returns arrayent_return_e.INVALID_MULTI_PROPERTY if this function is called butarrayent_config_t.device_can_multi_attribute is set to 0. Set it to 1 to suppress the error and enable multi-attribute messages. ACA returns arrayent_return_e.ARRAYENT_TIMEOUT if the function does not complete before the value specified in timeout. ACA returns ARRAYENT_MSG_TOO_BIG Solution: Always set len to the size of your buffer (data) before every call to ArrayentRecvMultiAttribute. Explanation: You may see this return code if you call this function multiple times without resetting len to the size of your buffer before every call. Consider the following scenario:

1. Host calls ArrayentRecvMultiAttribute(&data,&length,UINT32_MAX);, where data is a buffer 20 bytes long and length is sizeof(data).
2. ACA receives a 10 byte message from the cloud, stores it in data, and sets length to 10 (the size of the message).
3. Host calls ArrayentRecvMultiAttribute(&data,&length,UINT32_MAX); again. This time length equals 10 because that is what the ACA set it to in the last step.
4. ACA receives another message, this time 15 bytes long.
5. ACA returns ARRAYENT_MSG_TOO_BIG because the received message is 15 bytes long, but length is 10.

Parameters

Name	Data Type	Description
data	uint8_t*	Where to place the received multi-attribute message. The buffer is not touched if no message is received.
len	uint16_t*	Input: the length of the receive buffer. This buffer should be at least as long as the longest expected message. The longest possible multi-attribute message that the ACA can receive is 256 bytes. Output: If a multi-attribute message was received, this number is set by ACA library to the length of the data written to the data buffer. If no property message was received, this number is set to zero. In the event of an insufficiently sized receive buffer, this value will equal the size of the original buffer, the received message is truncated to the size of the buffer and an error is returned
timeout	uint32_t	Timeout for the receive operation to complete, in milliseconds. Providing a value of 0 instructs the ACA to return immediately.

Response

Data Type	Description
arrayent_return_e	Indicates if a multi-attribute message was received from the cloud.

ArrayentRecvProperty

Receive a property message.

Synopsis

arrayent_return_e ArrayentRecvProperty(char *data, uint16_t *len, uint32_t timeout)

Usage

This function listens for a property message from the Arrayent Cloud. It is blocking; it will not return until either a property message has been received from the server or the timeout argument has elapsed.
Warning Known issue (ACA versions 1.4.x and below only): if UDP is unavailable and the ACA must fall back onto TCP, this function may not work. You can determine if the ACA is using UDP or TCP by calling ArrayentNetStatus(&s) where s is an arrayent_net_status_t struct and checking the value of s.using_tcp. If s.using_tcp is set to 1 and you are experiencing issues with this function, it could be because of this known issue. This only applies to ACA versions 1.4.x and below. This is fixed in ACA version 1.5.0.

Postconditions

ACA returns ARRAYENT_MSG_TOO_BIG Solution: Always set len to the size of your buffer (data) before every call to ArrayentRecvProperty. Explanation: You may see this return code if you call this function multiple times without resetting len to the size of your buffer before every call. Consider the following scenario:

1. Host calls ArrayentRecvProperty(&data,&length,UINT32_MAX);, where data is a buffer 20 bytes long and length issizeof(data).
2. ACA receives a 10 byte message from the cloud, stores it in data, and sets length to 10 (the size of the message).
3. Host calls ArrayentRecvProperty(&data,&length,UINT32_MAX); again. This time length equals 10 because that is what the ACA set it to in the last step.
4. ACA receives another message, this time 15 bytes long.
5. ACA returns ARRAYENT_MSG_TOO_BIG because the received message is 15 bytes long, but length is 10.

Parameters

Name	Data Type	Description
data	char*	Upon success, data will contain a null-terminated, space-delimited string in the format of <KEY><VALUE>\0 where<KEY> is the name of a Device Attribute defined in your device data model and<VALUE> is the new value for that attribute. For example, if a web application sets a Device Attribute namedtemperature to 50, then data will contain the string temperature50\0.data is not touched if no message is received.
len	uint16_t*	Before calling ArrayentRecvProperty, the host application should set len to the maximum supported length (in characters) of the receive buffer. This value should be at least one character longer than the longest expected message, to allow for null-termination. Upon success, the ACA will set len to the length (in characters) of the data written to data. In the event of an insufficiently sized receive buffer, the received message is truncated to the maximum length (as specified by the host application) of the passed buffer. The value of len does not include the null terminator. If no property message was received, the ACA sets len to 0.
timeout	uint32_t	Timeout for the receive operation to complete, in milliseconds. Use 0 to indicate no wait.

Response

Data Type	Description
arrayent_return_e	Indicates if a property was received from the server.

ArrayentReqPropertyRefresh

Initiates an asynchronous request for the Arrayent Cloud to send down the current value of the specified property (A.K.A. Device Attribute).

Synopsis

arrayent_return_e ArrayentReqPropertyRefresh(char*property)

Preconditions

• The attribute which you are requesting has been defined in your Device Type.
• If your ACC is prior to 1.25.0, the attribute must be defined as a Hardware Attribute, otherwise the ACA API may still return success but the cloud will not send the attribute value to the device.

Postconditions

• Upon success the ACA returns arrayent_return_e.ARRAYENT_SUCCESS to your host application.
• The Arrayent Cloud has received the request to send down the current value of the specified property back to the device.
• The Arrayent Cloud will attempt to send down the current value of the attribute to the ACA.
• Your host application can retrieve the current value of the specified property via ArrayentRecvMultiAttribute() orArrayentRecvProperty().

Parameters

Name	Data Type	Description
property	char*	Pointer to the null-terminated attribute name.

Response

Data Type	Description
arrayent_return_e	Indicates if the request was successfully sent to the Arrayent Cloud. Use ArrayentRecvProperty() orArrayentRecvMultiAttribute() to retrieve the current value of the specified attribute.

ArrayentSendData

Send raw data with optional timeout.

Synopsis

arrayent_return_e ArrayentSendData(uint8_t *data, uint16_t data_type, uint16_t len)

Usage

This function sends raw data messages to the Arrayent Cloud synchronously. It is blocking, and will not return until a response message has been received from the cloud. In this context “raw data” means data that is structured in a format that is not natively supported by the Arrayent Cloud. Set data_type to 4 (which signifies binary data) unless instructed otherwise.

Preconditions

This function will not work unless your organization has coordinated with Arrayent to implement a parser in the Arrayent Cloud that converts your raw data to Arrayent Key-Value Pair format.

Parameters

Name	Data Type	Description
data	uint8_t*	Pointer to the data for transmission.
data_type	uint16_t	Data type of raw data being transmitted. Set to 4 (which signifies binary data) unless instructed otherwise.
len	uint16_t	Length of raw data payload.

Return Value

Data Type	Description
arrayent_return_e	Indicates if the data was sent to the cloud successfully.

ArrayentSetMultiAttribute

Write a multi-attribute message to the Arrayent Cloud.

Synopsis

arrayent_return_e ArrayentSetMultiAttribute(uint8_t *data,uint16_t len)

Usage

ArrayentSetMultiAttribute writes a multi-attribute message to the Arrayent Cloud. ACA support for unsigned integer data types was introduced in ACA 1.5. See Data Types Reference for more information about data types.

Preconditions

An enumerated alias has been defined in the Arrayent Cloud for every attribute that is being updated.

Limitations

Warning Entire multi-attribute message will be dropped if at least one attribute data type does not match.

Parameters

Name	Data Type	Description
data	uint8_t*	A buffer of attribute key-value pairs.
len	uint16_t	Length of data buffer. Maximum size 256 bytes.

Response

Data Type	Description
arrayent_return_e	Indicates if the attribute updates were written to the Arrayent Cloud database. Only returns success status when all attributes were successfully updated.

ArrayentSetProperty

Sends a single-attribute message to the Arrayent Cloud.

Synopsis

arrayent_return_e ArrayentSetProperty(char*property,char*value)

Postconditions

Failure: Returns arrayent_return_e.ARRAYENT_MSG_DATA_TOO_LONG if length of property and value combined exceeds maximum payload length. Payload length varies per platform, see Maximum Payload Lengths.

Parameters

Name	Data Type	Description
property	char*	Pointer to the property name. Null-terminated.
value	char*	Pointer to the property value. Null-terminated.

Response

Data Type	Description
arrayent_return_e	Indicates if the property was set correctly.

Data Structures

arrayent_return_e

Standard enum for returning the status of ACA function calls. See aca.h for a mapping of names to values.

Name	Description
ARRAYENT_SUCCESS	Command completed successfully.
ARRAYENT_FAILURE	Command failed.
ARRAYENT_TIMEOUT	Command failed: timed out.
ARRAYENT_INVALID_PRODUCT_ID	arrayent_config_t.product_id is invalid.
ARRAYENT_INVALID_PRODUCT_AES_KEY	arrayent_config_t.product_aes_key is invalid.
ARRAYENT_INVALID_LOAD_BALANCER	arrayent_config_t.load_balancer_domain_names[0], arrayent_config_t.load_balancer_domain_names[1], orarrayent_config_t.load_balancer_domain_names[2] is invalid. Format should be <subdomain>.arrayent.com.
ARRAYENT_INVALID_DEVICE_NAME	arrayent_config_t.device_name is invalid.
ARRAYENT_INVALID_DEVICE_PASSWORD	arrayent_config_t.device_password is invalid.
ARRAYENT_INVALID_DEVICE_AES_KEY	arrayent_config_t.device_aes_key is invalid.
ARRAYENT_INVALID_THREAD_PRIORITY	Device ACA thread priority is invalid.
ARRAYENT_INVALID_STACK_SIZE	Device ACA stack size is invalid.
ARRAYENT_NOT_CONFIGURED	Some required members of arrayent_config_t are invalid or not set.
ARRAYENT_NOT_INITIALIZED	ACA is not initialized. Call ArrayentInit().
ARRAYENT_NOT_CONNECTED	ACA is not connected to Arrayent Cloud.
ARRAYENT_INVALID_MULTI_PROPERTY	ACA is not configured to send / receive multi- attribute messages. Setarrayent_config_t.device_can_multi_attribute to 1.
ARRAYENT_OS_ERROR	OS / Interprocess communication error.
ARRAYENT_SERVER_ERROR	Arrayent Cloud responded with an error.
ARRAYENT_MSG_TOO_BIG	Payload exceeds maximum accepted size. See Maximum Payload Lengths.
ARRAYENT_INVALID_RESPONSE	Incorrect response received.
ARRAYENT_INVALID_IP_PROTOCOL	Value provided for arrayent_config_t.ip_protocol is invalid.

arrayent_sleep_level_e

Enum that the host application should use when calling ArrayentSleep().
Note Not in use before ACA version 1.4.

Name	Description
ARRAYENT_MIN_SLEEP_LEVEL	Arrayent threads are paused, and dynamic networking resources are torn down. On wake, networking resources are recreated and the Arrayent state machines resume with whatever state they were in prior to being put to sleep. If you are not sure which sleep level to use, default to this one.
ARRAYENT_DEEPSLEEP	Same as ARRAYENT_MIN_SLEEP_LEVEL. Future ACA versions may differentiate between the two.

arrayent_config_t

Member Name	Data Type	Default Value*	Description
product_id	uint16_t	None	The Product ID. This value is used to track what type of device is trying to connect to the Arrayent Cloud.
product_aes_key	constchar*	None	The Product Key. This is part of Arrayent’s device security protocol. This value is probably the same for all devices of this type of device. Null-terminated. Must be same length asARRAYENT_AES_KEY_LENGTH.
load_balancer_domain_names[3]	constchar*	None	A three element array. Each element contains a DNS name in the format ofexample.arrayent.com. These should be the device load balancer domain names, NOT the web service API domain names (sometimes the two components of the Arrayent Cloud share the same domain name, but the two components have separate domain names).“ArrayentConfigure“ does not check the valditiy of the provided DNS names. ThereforeArrayentConfigure may returnARRAYENT_SUCCESS even if these values are empty, wrong names or out of range values. Errors may be returned when callingArrayentInit and these values are used to connect to the cloud. Null-terminated. Length of each element must be less than ARRAYENT_LOAD_BALANCER_HOSTNAME_LENGTH.
load_balancer_udp_port	uint16_t	80	The UDP port that the ACA should attempt to connect to the load balancers on.
load_balancer_tcp_port	uint16_t	80	The TCP port that the ACA should attempt to connect to the load balancers on.
device_name	constchar*	None	Device Name. This is part of the device’s permanent, unique identifier, called its Device Code. This value must be unique to this individual device. Null-terminated. Case-sensitive. Length must be less thanARRAYENT_DEVICE_NAME_LENGTH.
device_password	constchar*	None	Device Password. This is part of the device’s permanent, unique identifier, called its Device Code. This value must be unique to this individual device. Null-terminated. Case-sensitive. Length must be less thanARRAYENT_DEVICE_PASSWORD_LENGTH.
device_aes_key	constchar*	None	The Device Key of the device. This is part of Arrayent’s device security protocol. This value must be unique to this individual device. Null-terminated. Must be same length asARRAYENT_AES_KEY_LENGTH.
device_can_multi_attribute	uint8_t	None	Setting to 1 indicates to the cloud that the cloud must send all attributes formatted in multi-attribute format. The host application may send attributes to the cloud usingArrayentSetProperty() orArrayentSetMultiAttribute() regardless of the value of this flag. But when this flag is set the host application MUST only retrieve attributes in multi-attribute format viaArrayentRecvMultiAttribute().
enable_logging	uint8_t	None	Reserved for internal Arrayent debugging.
aca_thread_priority	uint8_t	7	Indicates thread priority of the ACA. POSIX: Maximum = 0, Minimum = 0; WICED: Maximum = config MAX_PRIORITIES-1, Minimum = 0; WMSDK: Maximum =configMAX_PRIORITIES-1, Minimum = 0. After ArrayentInit() is called successfully, any subsequent modification to this value in a subsequent call to ArrayentConfigure() will be ignored.
aca_stack_size	uint16_t	Set by ACA	Stack size of ACA thread. This field is set by the ACA. It is not configurable.
data_message_endpoint	uint32_t	None	This field is reserved for Arrayent use and is set to a default value whenArrayentSetConfigDefaults is called. Do not set this field.
ip_protocol	uint8_t	255	The IP protocol to use. Only set this value to TCP for troubleshooting and development. TCP should not be used in production unless explicitly agreed upon with Arrayent. Options:17 (UDP only), 6 (TCP only), 255 (UDP by default; switch to TCP if UDP fails).
debug_level	uint8_t	None	Debug reporting level. Only effective with debug ACA builds.

* The default value is the value of the member after calling ArrayentSetConfigDefaults. If the Default Value is listed as “None” then the ACA does not set a default value for that member when ArrayentSetConfigDefaults is called.

arrayent_net_status_t

Name	Data Type	Length (bits)	Description
server_ip_obtained	uint8_t	1	ACA sets this to 1 when one of the DNS names the host application provided in arrayent_config_t.arrayent_load_balancer_domain_names array has been successfully resolved. This does not necessarily mean that the ACA has successfully found the IP address to the Arrayent Cloud! For example, if you supplied google.com for a DNS name, the ACA would be able to successfully resolve this DNS name and therefore the ACA would set server_ip_obtained to1.
heartbeats_ok	uint8_t	1	The ACA periodically sends keep-alive messages to the Arrayent Cloud. These are called heartbeats. When the ACA is able to send heartbeats to the cloud the value of this member is set to 1.
using_udp	uint8_t	1	ACA sets this to 1 when it is sending/receiving Internet data over UDP. Note that using_tcp and using_udpare usually not both simultaneously set to 1.
using_tcp	uint8_t	1	ACA sets this to 1 when it is sending/receiving Internet data over TCP. Note that using_tcp and using_udpare usually not both simultaneously set to 1.
connected_to_server	uint8_t	1	ACA sets this to 1 when it is successfully connected to the Arrayent Cloud. Don’t try to send messages to or receive messages from the cloud until this member is set to 1!
product_key_ok	uint8_t	1	The Product Key is one of two keys used for AES encryption. When the ACA attempts to log in to the Arrayent Cloud it will encrypt its initial login message with the Product Key. If the Product Key supplied by the ACA does not match the cloud’s Product Key, the cloud will reject the message. Note that the Product Key is initially passed to the ACA by the host application as arrayent_config_t.product_aes_key.
product_key_ok_username_bad	uint8_t	1	The Product Key which the ACA encrypted its login message with is OK, but the Device Name and Device Password that the host application provided to the ACA (arrayent_config_t.device_name and arrayent_config_t.device_password) are invalid.
login_successful	uint8_t	1	The ACA has successfully completed its initial login to the cloud. However, note that the ACA is not yet ready to send or receive messages! Only when arrayent_net_status_t.connected_to_server equals 1 can you start sending and receiving messages.
key_exchange_successful	uint8_t	1	Set to 1 after the ACA has completed its initial login request and exchanged AES encryption keys. When this member is set to 1 the ACA is almost ready to send and receive messages. But you should first check to make sure that arrayent_net_status_t.connected_to_server is set to 1.
sleep_mode	uint16_t	1	1 == ACA is sleeping. 0 == ACA is awake.
padding	uint16_t	6	Padding.
device_id	uint32_t	32	The session ID of the ACA’s current session in the Arrayent Cloud. This is a random integer.
service_endpoint_id	uint32_t	32	The component of the Arrayent Cloud which the ACA communicates with when ArrayentSetMultiAttributeor ArrayentSetProperty is called. This is mostly used internally by Arrayent for development and testing.
data_service_endpoint_id	uint32_t	32	The component of the Arrayent Cloud which the ACA communicates with when ArrayentSendData is called. This member is most used by Arrayent for development and testing.

arrayent_timestamp_t

Arrayent timestamp data type (output of ArrayentGetTime).

Member Name	Data Type	Description
year	uint16_t	4 digits. AD.
month	uint16_t	Valid options: 0 to 11. 0 = January, 1 = February, …
day	uint16_t	Valid options: 1 to 31.
hour	uint16_t	Valid options: 0 to 23. 0 = 12 A.M., 1 = 1 A.M., …, 23 = 11 P.M.
minute	uint16_t	Valid options: 0 to 59.
second	uint16_t	Valid options: 0 to 59.

Warning All members except day are 0-based.

Macros

Name	Description
ACA_VERSION_MAJOR	Incremented after ten minor versions.
ACA_VERSION_MINOR	Incremented on feature release.
ACA_VERSION_REVISION	Incremented on bug fix.
ACA_VERSION_SUBREVISION	Incremented internally.
ARRAYENT_AES_KEY_LENGTH	Length of AES keys.
ARRAYENT_NUM_LOAD_BALANCERS	Number of load balancers.
ARRAYENT_LOAD_BALANCER_HOSTNAME_LENGTH	Maximum length of load balancer domain name.
ARRAYENT_DEVICE_NAME_LENGTH	Maximum length of device name.
ARRAYENT_DEVICE_PASSWORD_LENGTH	Maximum length of device password.

Data Types Reference

See Data Types Reference.

Multi-Attribute Payload Format

Multi-attribute payloads are structured to the format outlined in this section.

NUM

Attribute 1

Attribute 2

Attribute …

Attribute N

The first byte of the payload is an unsigned integer representing the number of attribute key-value pairs contained in the payload. Each attribute key-value pair is structured as follows:

Enumerated Alias

Data Type

Attribute Value

Enumerated Alias is an unsigned integer byte which represents an attribute in your Device Type. This value must match the “Enumerated Alias” field of the Arrayent Cloud’s definition of the attribute.
Warning If you have not defined an enumerated alias for the attribute, then this first byte will have a value of 0. The following data will be the null-terminated string name of the attribute.
Data Type is a single unsigned integer byte which represents the data type of the following attribute value. Attribute Value contains the current value of the attribute. The length and format of this is dependent upon the data type of the value. Strings must be null terminated. All other value types are fixed length.
Warning For Arrayent Cloud versions 1.3 and above: when sending a multi-attribute message from your embedded host application to the Arrayent Connect Agent or Arrayent Connect Module, the data type field and and attribute value fields in your multi-attribute payload must match the attribute’s data type as they are defined in the Arrayent Cloud.
See Data Types Reference for more information on all of the available data types for Device Attributes.

Maximum Payload Lengths

The table below documents the maximum message payload lengths for each of the ACA’s supported platforms. Host applications and web applications must never send messages with payloads larger than the maximums listed below.

Platform	Maximum Payload Length (Bytes)
Broadcom BCM943362WCD4 + WICED SDK 2.4.0.0	256
Marvell 88MC200 + WMSDK 2.13.82	256
Ralink RT5350 + Ralink SDK	256
Linux x86 3.X + gcc / glibc 2	1024
Linux AT91SAM9G + gcc / glibc 2	1024
Raspbian BCM2835 + gcc / glibc 2	256