Communicating with a Smartstrap.
Smartstrap APIs allow Pebble watches to communicate with electronics connected to the watch through the accessory port.
Apps communicate with smartstraps by manipulating the attributes which the smartstrap supports or by reading and writing raw data using the raw data attribute (see SMARTSTRAP_RAW_DATA_SERVICE_ID and SMARTSTRAP_RAW_DATA_ATTRIBUTE_ID). A service is a collection of attributes which may be supported by a smartstrap. Once a smartstrap is connected, the availability handler will be called (if subscribed) for each service which is supported by the smartstrap. Then, the app may make read and write requests to attributes within that service on the smartstrap.
Performing a read request on an attribute will cause the did_read handler to be called for the attribute when either a valid response is received from the smartstrap, or some error (i.e. a timeout) occurs.
Performing a write request on an attribute will cause the did_write handler to be called for the attribute when the write is completed or an error occurs.
When either the first attribute is created (see smartstrap_attribute_create), or an availability_did_change handler is subscribed (see smartstrap_subscribe), whichever comes first, power will be applied to the smartstrap, and connection establishment will begin. As part of the connection establishment, the smartstrap will report the services which it supports, at which point the smartstrap APIs will report them as being available and allow requests to be issued. If all created attributes are destroyed (see smartstrap_attribute_destroy) and the availability_did_change handler is unsubscribed (see smartstrap_unsubscribe), power will no longer be applied to the smartstrap and the services which it supported will no longer be available.
Multiple attributes may have a read or write request pending at any given time, but individual attributes may only have a single request (either read or write) pending at any given time.
Calls made to smartstrap_attribute_create on a platform that does not support smartstraps will return NULL. Other calls will do nothing, and return SmartstrapResultNotPresent if possible.
For code samples, a list of available attributes, and technical details of the Smartstrap protocol, see the Building Smartstraps Guide.
The function smartstrap_subscribe does not exist in SDK 3.
Subscribes handlers to be called after certain smartstrap events occur.
Registering an availability_did_change handler will cause power to be applied to the smartstrap port and connection establishment to begin.
SmartstrapResultNotPresent if the watch does not have a smartstrap port or SmartstrapResultOk otherwise.
The function smartstrap_unsubscribe does not exist in SDK 3.
Unsubscribes the handlers. The handlers will no longer be called, but in-flight requests will otherwise be unaffected.
If power was being applied to the smartstrap port and there are no attributes have been created (or they have all been destroyed), this will cause the smartstrap power to be turned off.
The function smartstrap_set_timeout does not exist in SDK 3.
Changes the value of the timeout which is used for smartstrap requests. This timeout is started after the request is completely sent to the smartstrap and will be canceled only if the entire response is received before it triggers. The new timeout value will take affect only for requests made after this API is called.
The maximum allowed timeout is currently 1000ms. If a larger value is passed, it will be internally lowered to the maximum.
The duration of the timeout to set, in milliseconds.
The function smartstrap_attribute_create does not exist in SDK 3.
Creates and returns a SmartstrapAttribute for the specified service and attribute. This API will allocate an internal buffer of the requested length on the app's heap.
Creating an attribute will result in power being applied to the smartstrap port (if it isn't already) and connection establishment to begin.
The ServiceId to create the attribute for.
The AttributeId to create the attribute for.
The length of the internal buffer which will be used to store the read and write requests for this attribute.
The newly created SmartstrapAttribute or NULL if an internal error occured or if the specified length is greater than SMARTSTRAP_ATTRIBUTE_LENGTH_MAXIMUM.
The function smartstrap_attribute_destroy does not exist in SDK 3.
Destroys a SmartstrapAttribute. No further handlers will be called for this attribute and it may not be used for any future requests.
If power was being applied to the smartstrap port, no availability_did_change handler is subscribed, and the last attribute is being destroyed, this will cause the smartstrap power to be turned off.
The SmartstrapAttribute which should be destroyed.
The function smartstrap_service_is_available does not exist in SDK 3.
Checks whether or not the specified service is currently supported by a connected smartstrap.
The SmartstrapServiceId of the service to check for availability.
Whether or not the service is available.
The function smartstrap_attribute_get_service_id does not exist in SDK 3.
Returns the ServiceId which the attribute was created for (see smartstrap_attribute_create).
The SmartstrapAttribute for which to obtain the service ID.
The SmartstrapServiceId which the attribute was created with.
The function smartstrap_attribute_get_attribute_id does not exist in SDK 3.
Gets the AttributeId which the attribute was created for (see smartstrap_attribute_create).
The SmartstrapAttribute for which to obtain the attribute ID.
The SmartstrapAttributeId which the attribute was created with.
The function smartstrap_attribute_read does not exist in SDK 3.
Performs a read request for the specified attribute. The did_read callback will be called when the response is received from the smartstrap or when an error occurs.
The attribute to be perform the read request on.
SmartstrapResultOk if the read operation was started. The did_read callback will be called once the read request has been completed.
The function smartstrap_attribute_begin_write does not exist in SDK 3.
Begins a write request for the specified attribute and returns a buffer into which the app should write the data before calling smartstrap_attribute_end_write.
The buffer must not be used after smartstrap_attribute_end_write is called.
The attribute to begin writing for.
The buffer to write the data into.
The length of the buffer in bytes.
SmartstrapResultOk if a write operation was started and the buffer and buffer_length parameters were set, or an error otherwise.
The function smartstrap_attribute_end_write does not exist in SDK 3.
This should be called by the app when it is done writing to the buffer provided by smartstrap_begin_write and the data is ready to be sent to the smartstrap.
The attribute to begin writing for.
The length of the data to be written, in bytes.
Whether or not a read request on this attribute should be automatically triggered following a successful write request.
SmartstrapResultOk if a write operation was queued to be sent to the smartstrap. The did_write handler will be called when the request is written to the smartstrap, and if request_read was set to true, the did_read handler will be called when the read is complete.
The struct SmartstrapHandlers does not exist in SDK 3.
Handlers which are passed to smartstrap_subscribe.
The connection handler is called after the connection state changes.
The read handler is called whenever a read is complete or the read times-out.
The did_write handler is called when a write has completed.
The notified handler is called whenever a notification is received for an attribute.
The enum SmartstrapResult does not exist in SDK 3.
Error values which may be returned from the smartstrap APIs.
No error occured.
Invalid function arguments were supplied.
The smartstrap port is not present on this watch.
A request is already pending on the specified attribute.
Either a smartstrap is not connected or the connected smartstrap does not support the specified service.
The smartstrap reported that it does not support the requested attribute.
A time-out occured during the request.
The typedef SmartstrapServiceId does not exist in SDK 3.
A type representing a smartstrap ServiceId.
The typedef SmartstrapAttribute does not exist in SDK 3.
A type representing an attribute of a service provided by a smartstrap. This type is used when issuing requests to the smartstrap.
The typedef SmartstrapAttributeId does not exist in SDK 3.
A type representing a smartstrap AttributeId.
The typedef SmartstrapServiceAvailabilityHandler does not exist in SDK 3.
The type of function which is called after the smartstrap connection status changes.
The ServiceId for which the availability changed.
Whether or not this service is now available.
The typedef SmartstrapReadHandler does not exist in SDK 3.
The type of function which can be called when a read request is completed.
Any write request made to the same attribute within this function will fail with SmartstrapResultBusy.
The attribute which was read.
The result of the read.
The data read from the smartstrap or NULL if the read was not successful.
The length of the data or 0 if the read was not successful.
The typedef SmartstrapWriteHandler does not exist in SDK 3.
The type of function which can be called when a write request is completed.
The attribute which was written.
The result of the write.
The typedef SmartstrapNotifyHandler does not exist in SDK 3.
The type of function which can be called when the smartstrap sends a notification to the watch.
The attribute which the notification came from.
The define SMARTSTRAP_TIMEOUT_DEFAULT does not exist in SDK 3.
The default request timeout in milliseconds (see smartstrap_set_timeout).
The define SMARTSTRAP_RAW_DATA_SERVICE_ID does not exist in SDK 3.
The service_id to specify in order to read/write raw data to the smartstrap.
The define SMARTSTRAP_RAW_DATA_ATTRIBUTE_ID does not exist in SDK 3.
The attribute_id to specify in order to read/write raw data to the smartstrap.
Do you have questions about the Pebble SDK?
Do you need some help understanding something on this page?
You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!