pebble
  • Tutorials
  • Get the SDK
  • Guides
  • Documentation
  • Examples
  • Community
  • Blog
  • More
Privacy
Cookies
Publish

Pebble C API

  • Pebble C API
  • Pebble JavaScript API
  • PebbleKit JS
  • PebbleKit iOS
  • PebbleKit Android
  • Foundation
    • App
    • App Communication
    • App Glance
    • AppMessage
    • AppSync
    • AppWorker
    • DataLogging
    • DataStructures
      • UUID
    • Dictation
    • Dictionary
    • Event Service
      • AccelerometerService
      • AppFocusService
      • BatteryStateService
      • CompassService
      • ConnectionService
      • HealthService
      • TickTimerService
    • Exit Reason
    • Internationalization
    • Launch Reason
    • Logging
    • Math
    • Memory Management
    • Platform
    • Resources
      • File Formats
    • Storage
    • Timer
    • Wakeup
    • Wall Time
    • WatchInfo
    • Rocky
  • Graphics
    • Draw Commands
    • Drawing Paths
    • Drawing Primitives
    • Drawing Text
    • Fonts
    • Graphics Context
    • Graphics Types
      • Color Definitions
  • User Interface
    • Animation
      • PropertyAnimation
    • Clicks
    • Layers
      • ActionBarLayer
      • BitmapLayer
      • MenuLayer
      • RotBitmapLayer
      • ScrollLayer
      • SimpleMenuLayer
      • StatusBarLayer
      • TextLayer
    • Light
    • Preferences
    • UnobstructedArea
    • Vibes
    • Window
      • ActionMenu
      • NumberWindow
    • Window Stack
  • Standard C
    • Format
    • Locale
    • Math
    • Memory
    • String
    • Time

Smartstrap

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.

Function Documentation

  • SDK 3
  • SDK 4

The function smartstrap_subscribe does not exist in SDK 3.

SmartstrapResult smartstrap_subscribe(SmartstrapHandlers handlers)

Subscribes handlers to be called after certain smartstrap events occur.

Note

Registering an availability_did_change handler will cause power to be applied to the smartstrap port and connection establishment to begin.

Returns

SmartstrapResultNotPresent if the watch does not have a smartstrap port or SmartstrapResultOk otherwise.

See Also

smartstrap_unsubscribe
  • SDK 3
  • SDK 4

The function smartstrap_unsubscribe does not exist in SDK 3.

void smartstrap_unsubscribe(void)

Unsubscribes the handlers. The handlers will no longer be called, but in-flight requests will otherwise be unaffected.

Note

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.

  • SDK 3
  • SDK 4

The function smartstrap_set_timeout does not exist in SDK 3.

void smartstrap_set_timeout(uint16_t timeout_ms)

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.

Note

The maximum allowed timeout is currently 1000ms. If a larger value is passed, it will be internally lowered to the maximum.

Parameters

timeout_ms

The duration of the timeout to set, in milliseconds.

See Also

SMARTSTRAP_TIMEOUT_DEFAULT
  • SDK 3
  • SDK 4

The function smartstrap_attribute_create does not exist in SDK 3.

SmartstrapAttribute * smartstrap_attribute_create(SmartstrapServiceId service_id, SmartstrapAttributeId attribute_id, size_t buffer_length)

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.

Note

Creating an attribute will result in power being applied to the smartstrap port (if it isn't already) and connection establishment to begin.

Parameters

service_id

The ServiceId to create the attribute for.

attribute_id

The AttributeId to create the attribute for.

buffer_length

The length of the internal buffer which will be used to store the read and write requests for this attribute.

Returns

The newly created SmartstrapAttribute or NULL if an internal error occured or if the specified length is greater than SMARTSTRAP_ATTRIBUTE_LENGTH_MAXIMUM.

  • SDK 3
  • SDK 4

The function smartstrap_attribute_destroy does not exist in SDK 3.

void smartstrap_attribute_destroy(SmartstrapAttribute * attribute)

Destroys a SmartstrapAttribute. No further handlers will be called for this attribute and it may not be used for any future requests.

Note

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.

Parameters

attribute (in)

The SmartstrapAttribute which should be destroyed.

  • SDK 3
  • SDK 4

The function smartstrap_service_is_available does not exist in SDK 3.

bool smartstrap_service_is_available(SmartstrapServiceId service_id)

Checks whether or not the specified service is currently supported by a connected smartstrap.

Parameters

service_id

The SmartstrapServiceId of the service to check for availability.

Returns

Whether or not the service is available.

  • SDK 3
  • SDK 4

The function smartstrap_attribute_get_service_id does not exist in SDK 3.

SmartstrapServiceId smartstrap_attribute_get_service_id(SmartstrapAttribute * attribute)

Returns the ServiceId which the attribute was created for (see smartstrap_attribute_create).

Parameters

attribute

The SmartstrapAttribute for which to obtain the service ID.

Returns

The SmartstrapServiceId which the attribute was created with.

  • SDK 3
  • SDK 4

The function smartstrap_attribute_get_attribute_id does not exist in SDK 3.

SmartstrapAttributeId smartstrap_attribute_get_attribute_id(SmartstrapAttribute * attribute)

Gets the AttributeId which the attribute was created for (see smartstrap_attribute_create).

Parameters

attribute

The SmartstrapAttribute for which to obtain the attribute ID.

Returns

The SmartstrapAttributeId which the attribute was created with.

  • SDK 3
  • SDK 4

The function smartstrap_attribute_read does not exist in SDK 3.

SmartstrapResult smartstrap_attribute_read(SmartstrapAttribute * attribute)

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.

Parameters

attribute

The attribute to be perform the read request on.

Returns

SmartstrapResultOk if the read operation was started. The did_read callback will be called once the read request has been completed.

  • SDK 3
  • SDK 4

The function smartstrap_attribute_begin_write does not exist in SDK 3.

SmartstrapResult smartstrap_attribute_begin_write(SmartstrapAttribute * attribute, uint8_t ** buffer, size_t * buffer_length)

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.

Note

The buffer must not be used after smartstrap_attribute_end_write is called.

Parameters

attribute (in)

The attribute to begin writing for.

buffer (out)

The buffer to write the data into.

buffer_length (out)

The length of the buffer in bytes.

Returns

SmartstrapResultOk if a write operation was started and the buffer and buffer_length parameters were set, or an error otherwise.

  • SDK 3
  • SDK 4

The function smartstrap_attribute_end_write does not exist in SDK 3.

SmartstrapResult smartstrap_attribute_end_write(SmartstrapAttribute * attribute, size_t write_length, bool request_read)

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.

Parameters

attribute (in)

The attribute to begin writing for.

write_length

The length of the data to be written, in bytes.

request_read

Whether or not a read request on this attribute should be automatically triggered following a successful write request.

Returns

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.

Data Structure Documentation

  • SDK 3
  • SDK 4

The struct SmartstrapHandlers does not exist in SDK 3.

struct SmartstrapHandlers

Handlers which are passed to smartstrap_subscribe.

Data Fields

SmartstrapServiceAvailabilityHandler availability_did_change

The connection handler is called after the connection state changes.

SmartstrapReadHandler did_read

The read handler is called whenever a read is complete or the read times-out.

SmartstrapWriteHandler did_write

The did_write handler is called when a write has completed.

SmartstrapNotifyHandler notified

The notified handler is called whenever a notification is received for an attribute.

Enum Documentation

  • SDK 3
  • SDK 4

The enum SmartstrapResult does not exist in SDK 3.

enum SmartstrapResult

Error values which may be returned from the smartstrap APIs.

Enumerators

SmartstrapResultOk

No error occured.

SmartstrapResultInvalidArgs

Invalid function arguments were supplied.

SmartstrapResultNotPresent

The smartstrap port is not present on this watch.

SmartstrapResultBusy

A request is already pending on the specified attribute.

SmartstrapResultServiceUnavailable

Either a smartstrap is not connected or the connected smartstrap does not support the specified service.

SmartstrapResultAttributeUnsupported

The smartstrap reported that it does not support the requested attribute.

SmartstrapResultTimeOut

A time-out occured during the request.

Typedef Documentation

  • SDK 3
  • SDK 4

The typedef SmartstrapServiceId does not exist in SDK 3.

typedef uint16_t SmartstrapServiceId

A type representing a smartstrap ServiceId.

  • SDK 3
  • SDK 4

The typedef SmartstrapAttribute does not exist in SDK 3.

typedef struct SmartstrapAttribute SmartstrapAttribute

A type representing an attribute of a service provided by a smartstrap. This type is used when issuing requests to the smartstrap.

  • SDK 3
  • SDK 4

The typedef SmartstrapAttributeId does not exist in SDK 3.

typedef uint16_t SmartstrapAttributeId

A type representing a smartstrap AttributeId.

  • SDK 3
  • SDK 4

The typedef SmartstrapServiceAvailabilityHandler does not exist in SDK 3.

typedef void(* SmartstrapServiceAvailabilityHandler)(SmartstrapServiceId service_id, bool is_available)

The type of function which is called after the smartstrap connection status changes.

Parameters

service_id

The ServiceId for which the availability changed.

is_available

Whether or not this service is now available.

  • SDK 3
  • SDK 4

The typedef SmartstrapReadHandler does not exist in SDK 3.

typedef void(* SmartstrapReadHandler)(SmartstrapAttribute *attribute, SmartstrapResult result, const uint8_t *data, size_t length)

The type of function which can be called when a read request is completed.

Note

Any write request made to the same attribute within this function will fail with SmartstrapResultBusy.

Parameters

attribute

The attribute which was read.

result

The result of the read.

data

The data read from the smartstrap or NULL if the read was not successful.

length

The length of the data or 0 if the read was not successful.

  • SDK 3
  • SDK 4

The typedef SmartstrapWriteHandler does not exist in SDK 3.

typedef void(* SmartstrapWriteHandler)(SmartstrapAttribute *attribute, SmartstrapResult result)

The type of function which can be called when a write request is completed.

Parameters

attribute

The attribute which was written.

result

The result of the write.

  • SDK 3
  • SDK 4

The typedef SmartstrapNotifyHandler does not exist in SDK 3.

typedef void(* SmartstrapNotifyHandler)(SmartstrapAttribute *attribute)

The type of function which can be called when the smartstrap sends a notification to the watch.

Parameters

attribute

The attribute which the notification came from.

Macro Definition Documentation

  • SDK 3
  • SDK 4

The define SMARTSTRAP_TIMEOUT_DEFAULT does not exist in SDK 3.

#define SMARTSTRAP_TIMEOUT_DEFAULT 250

The default request timeout in milliseconds (see smartstrap_set_timeout).

  • SDK 3
  • SDK 4

The define SMARTSTRAP_RAW_DATA_SERVICE_ID does not exist in SDK 3.

#define SMARTSTRAP_RAW_DATA_SERVICE_ID 0

The service_id to specify in order to read/write raw data to the smartstrap.

  • SDK 3
  • SDK 4

The define SMARTSTRAP_RAW_DATA_ATTRIBUTE_ID does not exist in SDK 3.

#define SMARTSTRAP_RAW_DATA_ATTRIBUTE_ID 0

The attribute_id to specify in order to read/write raw data to the smartstrap.

  • SDK 3
  • SDK 4

The define PBL_IF_SMARTSTRAP_ELSE does not exist in SDK 3.

#define PBL_IF_SMARTSTRAP_ELSE ( if_true, if_false)

Convenience macro to switch between two expressions depending on smartstrap support. On platforms with a smartstrap the first expression will be chosen, the second otherwise.

Need some help?

Functions

  • smartstrap_subscribe
  • smartstrap_unsubscribe
  • smartstrap_set_timeout
  • smartstrap_attribute_create
  • smartstrap_attribute_destroy
  • smartstrap_service_is_available
  • smartstrap_attribute_get_service_id
  • smartstrap_attribute_get_attribute_id
  • smartstrap_attribute_read
  • smartstrap_attribute_begin_write
  • smartstrap_attribute_end_write

Data Structures

  • SmartstrapHandlers

Enums

  • SmartstrapResult

Typedefs

  • SmartstrapServiceId
  • SmartstrapAttribute
  • SmartstrapAttributeId
  • SmartstrapServiceAvailabilityHandler
  • SmartstrapReadHandler
  • SmartstrapWriteHandler
  • SmartstrapNotifyHandler

Macro Defintions

  • SMARTSTRAP_TIMEOUT_DEFAULT
  • SMARTSTRAP_RAW_DATA_SERVICE_ID
  • SMARTSTRAP_RAW_DATA_ATTRIBUTE_ID
  • PBL_IF_SMARTSTRAP_ELSE

Getting Help

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!