pebble-firmware/sdk/docs/common.dox

/**

@defgroup Foundation Foundation
\brief The core of the Pebble SDK

The Pebble SDK consists of different frameworks that are organized by functionality.
Each framework includes an API and provides access to the software libraries supported
natively by Pebble OS. You use these interfaces (APIs) in the C programming
language to write software for the Pebble platform.

Frameworks are grouped hierarchically into Foundation, Graphics, Standard C and User Interface.

The Foundation framework is the core of the Pebble OS.

@defgroup Graphics Graphics
\brief Low-level drawing routines

The Graphics framework defines a set of APIs that can be used to draw paths, primitives and text,
as well as handle the loading of fonts and the setting of graphics contexts for compositing, fill color
and text color.

@defgroup Smartstrap
\brief 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 \ref
SMARTSTRAP_RAW_DATA_SERVICE_ID and \ref 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 \ref smartstrap_attribute_create), or an
availability_did_change handler is subscribed (see \ref 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 \ref smartstrap_attribute_destroy) and the
availability_did_change handler is unsubscribed (see \ref 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 \ref 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
<a href="//developer.getpebble.com/guides/hardware/">Building Smartstraps Guide</a>.

@defgroup UI User Interface
\brief Everything related to user interface

The User Interface framework enables your Pebble watchface or watchapp to handle basic UI components,
like clicks, layers, vibes, windows and window stacks.

@defgroup Fonts Fonts
\brief Custom and system fonts


Pebble OS provides you with a wide range of system fonts that you can use when you need to display and
render text or numbers in your Pebble watchface or watchapp.

If you want to use a system font, you call fonts_get_system_font() and simply pass it the name of the
system font you want.

To use a custom font, call fonts_load_custom_font(). The sample code feature_custom_font shows how you can
do this programmatically, using a font resource to convert a TrueType font into a rasterized version of that
font at a specified font size.

For example:

\code{.c}
GFont custom_font = fonts_load_custom_font
   (resource_get_handle(RESOURCE_ID_FONT_OSP_DIN_44));
\endcode

Raster Gothic Condensed is the font used throughout the Pebble system, largely because it is optimized
for monochromatic displays. Pebble selected this font because it allows a relatively large number of
characters to be displayed on a single line, also because the font has an excellent readability vs. size ratio.

Refer to the chapter \htmlinclude UsingResources.html which explains how to work with font resources and embed
a font into your app.

@defgroup Math Math
\brief Math routines.

Below is a code example that uses the trigonometry functions to calculate the coordinate at which
the second hand of a watch ends, using seconds from the system time.
\code{.c}
GPoint secondHand;
GPoint center;
struct tm *tick_time = ...;
int32_t secondHandLength = ...;
...
int32_t second_angle = TRIG_MAX_ANGLE * tick_time->tm_sec / 60;
secondHand.y = (-cos_lookup(second_angle) * secondHandLength / TRIG_MAX_RATIO) + center.y;
secondHand.x = (sin_lookup(second_angle) * secondHandLength / TRIG_MAX_RATIO) + center.x;
\endcode


@defgroup EventService Event Service
\brief APIs to handle event services

Pebble OS provides you with a set of APIs for handling event services, like accelerometer taps, app focus
for interactivity, battery states, Bluetooth connections, and tick timers to call when a time component has
changed. You use event services to be notified, for example, when something happens on Pebble, like losing
the connection to the phone or when a notification covers the screen and requires your Pebble game to pause.

@defgroup App App
\brief App entry point and event loop.


App is a module that provides you with an event loop for your Pebble app.
All interaction between Pebble apps and the underlying Pebble OS takes place through an event loop.
Before calling the \ref app_event_loop() function, you subscribe to event services and implement event handlers.
Each handler receives specific types of Events dispatched throughout the life of the Pebble watchapp.

The \ref app_event_loop() function takes care of both waiting for new events to become available on the
watchapp event bus and routing new events to the appropriate handler. \ref EventService allows an app to
directly register for different types of events. This function will block until the watchapp is ready
to exit, and should be placed in the app's main() function.

A watchapp typically configures and uses the \ref app_event_loop() as follows:

\code{.c}
int main(void) {
  // do set up here

  // Enter the main event loop. This will block until the app is ready to exit.
  app_event_loop();

  // do clean up here
}
\endcode

@defgroup StandardC Standard C
\brief Standard C types, functions, constants, etc.
The standard C functions available here, such as \ref snprintf() and \ref time(), are provided by the firmware. Using these functions will not significantly increase the size of your app beyond what is needed to call the function. You may use other standard C functions not listed here, but be aware that not all will successfully be added to your app, and if they are added, your app's binary size will increase accordingly.

@addtogroup StandardC
@{

@defgroup StandardMath Math
\brief Standard math functions.

@addtogroup StandardMath
@{

\fn int rand()
\brief Generate a pseudo-random integer between 0 and \ref RAND_MAX inclusive. This function can be seeded by \ref srand().

A simple way to change the range to be an integer between 0 and n-1 inclusive is using \% e.g. `rand() % n`.

\return The pseudo-randomly generated number

\fn void srand(unsigned int seed)
\brief Seed the pseudo-random number generator.

When your app starts, the pseudo-random number generator is automatically seeded with a random number that is generated by a high-entropy hardware random number generator.

This function affects subsequent calls to \ref rand() to produce a sequence of numbers for a given seed value. You can use this to either create a different sequence of numbers by always using a different seed or to obtain the same sequence of numbers by reusing the same seed.
\param seed The source number used to generate a sequence of pseudo-random numbers

\def RAND_MAX
\brief The maximum integer value \ref rand() may return.

@}

@defgroup StandardLocale Locale
\brief Standard locale functions.

@addtogroup StandardLocale
@{
\fn char *setlocale(int category, char *locale)
\brief Set the app's locale for a category of routines.

`setlocale` can be used to:
  - set the app's locale to a specific locale: `setlocale(LC_ALL, "en_CA")`
  - set the app's locale to the system locale: `setlocale(LC_ALL, "")`
  - get the app's curent locale: `setlocale(LC_ALL, NULL)`

\param category The category of routines for which to set the locale
\param locale The ISO formatted locale to use, or "" for the system locale
\return the locale after the change is applied, NULL on failure (e.g. unsuported category)
\note Currently, we only support two categories: LC_ALL and LC_TIME

@}

@defgroup StandardMemory Memory
\brief Standard memory functions.

@addtogroup StandardMemory
@{

\fn void *malloc(size_t size)
\brief Allocates a requested amount of memory.
\param size The number of bytes to allocate
\return A pointer to the allocated memory or NULL on error.

\fn void free(void *ptr)
\brief Frees previously allocated memory.
\param ptr The memory buffer to free.

\fn void *calloc(size_t count, size_t size)
\brief Allocates space for count objects that are size bytes and fills the
memory with bytes of value 0
\param count The number of objects to allocate space for
\param size The size of the object type being allocated
\return A pointer to the allocated memory or NULL on error.

\fn void *realloc(void *ptr, size_t size)
\brief Takes the memory allocated at ptr and changes the length of its
allocation to the size specified. Copies the smaller of the length of the
original allocation or the new size into the newly allocated buffer.
\param ptr The memory allocation to be changed
\param size The size to change the ptr allocation to
\return A pointer to the new allocated memory or NULL on error

\fn int memcmp(const void *ptr1, const void *ptr2, size_t n)
\brief Compares the first n bytes of memory regions ptr1 and ptr2
\param ptr1 The pointer to the first memory region to compare
\param ptr2 The pointer to the second memory region to compare
\param n The number of bytes to compare
\return 0 if the first n bytes of ptr1 and ptr 2 match. Otherwise, the sign is determined by the sign of the difference between the first pair of bytes that differ in ptr1 and ptr2.

\fn void *memcpy(void *dest, const void *src, size_t n)
\brief Copies n bytes from src to dest.
\param dest The pointer to the destination memory region
\param src The pointer to the source memory region
\param n The number of bytes to copy

\fn void *memmove(void *dest, const void *src, size_t n);
\brief Copies n bytes from src to dest by first copying to a temporary area first, allowing dest and src to potentially overlap. This can be used to move data to a location that overlaps its previous location.
\param dest The pointer to the destination memory region
\param src The pointer to the source memory region
\param n The number of bytes to copy

\fn void *memset(void *dest, int c, size_t n);
\brief Sets n bytes to c starting at dest. This can be used to clear a memory region for example if c is 0.
\param dest The pointer to the destination memory region
\param c The integer used as an unsigned char to assign to each byte
\param n The number of bytes to set

\typedef size_t
\brief size as an unsigned integer

@}

@defgroup StandardIO Format
\brief Standard formatting. If you're looking for input/output functions, check out the \ref Logging API.

@addtogroup StandardIO
@{

\fn int snprintf(char *str, size_t n, const *fmt, ...);
\brief Format a string into a buffer. The Pebble-supported format specifiers are displayed below.

\param str The string buffer to write the formatted string into
\param n The maximum size of the buffer
\param fmt The C formatting string
\return The number of bytes written

\htmlonly
<style type="text/css">
.tg  {border-collapse:collapse;border-spacing:0;}
.tg td{font-family:Arial, sans-serif;font-size:14px;padding:10px 5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;}
.tg th{font-family:Arial, sans-serif;font-size:14px;font-weight:normal;padding:10px 5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;}
</style>
<table class="tg">
  <tr>
    <th class="tg-031e">Specifier</th>
    <th class="tg-031e">Output</th>
    <th class="tg-031e">Example</th>
  </tr>
  <tr>
    <td class="tg-031e">d or i</td>
    <td class="tg-031e">Signed decimal integer</td>
    <td class="tg-031e">294<br>-294</td>
  </tr>
  <tr>
    <td class="tg-031e">u</td>
    <td class="tg-031e">Unsigned decimal integer</td>
    <td class="tg-031e">7235</td>
  </tr>
  <tr>
    <td class="tg-031e">o</td>
    <td class="tg-031e">Unsigned octal</td>
    <td class="tg-031e">610</td>
  </tr>
  <tr>
    <td class="tg-031e">x</td>
    <td class="tg-031e">Unsigned hexadecimal integer</td>
    <td class="tg-031e">8b2</td>
  </tr>
  <tr>
    <td class="tg-031e">X</td>
    <td class="tg-031e">Unsigned hexadecimal integer (uppercase)</td>
    <td class="tg-031e">8B2</td>
  </tr>
  <tr>
    <td class="tg-031e">c</td>
    <td class="tg-031e">Character</td>
    <td class="tg-031e">h</td>
  </tr>
  <tr>
    <td class="tg-031e">s</td>
    <td class="tg-031e">Null-terminated string of characters</td>
    <td class="tg-031e">pebble</td>
  </tr>
  <tr>
    <td class="tg-031e">p</td>
    <td class="tg-031e">Pointer address</td>
    <td class="tg-031e">0xb8000000</td>
  </tr>
  <tr>
    <td class="tg-031e">%</td>
    <td class="tg-031e">A % followed by another % character will write a single % to the stream.</td>
    <td class="tg-031e">%</td>
  </tr>
</table>
<br>
\endhtmlonly

\details Length specifiers can also be combined with the format specifiers above:

\htmlonly
<style type="text/css">
.tg  {border-collapse:collapse;border-spacing:0;}
.tg td{font-family:Arial, sans-serif;font-size:14px;padding:10px 5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;}
.tg th{font-family:Arial, sans-serif;font-size:14px;font-weight:normal;padding:10px 5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;}
.tg .tg-s6z2{text-align:center}
</style>
<table class="tg">
  <tr>
    <th class="tg-031e"></th>
    <th class="tg-s6z2">u o x X</th>
    <th class="tg-s6z2">c</th>
    <th class="tg-s6z2">s</th>
    <th class="tg-s6z2">p</th>
    <th class="tg-s6z2">n</th>
  </tr>
  <tr>
    <td class="tg-031e">(none)</td>
    <td class="tg-031e">unsigned int</td>
    <td class="tg-031e">int</td>
    <td class="tg-031e">char*</td>
    <td class="tg-031e">void*</td>
    <td class="tg-031e">int*</td>
  </tr>
  <tr>
    <td class="tg-031e">h</td>
    <td class="tg-031e">unsigned short int</td>
    <td class="tg-031e"></td>
    <td class="tg-031e"></td>
    <td class="tg-031e"></td>
    <td class="tg-031e">short int*</td>
  </tr>
  <tr>
    <td class="tg-031e">l</td>
    <td class="tg-031e">unsigned long int</td>
    <td class="tg-031e">wint_t</td>
    <td class="tg-031e">wchar_t*</td>
    <td class="tg-031e"></td>
    <td class="tg-031e">long int*</td>
  </tr>
</table>
\endhtmlonly

@}

@defgroup StandardString String
\brief Standard C-string manipulation.

@addtogroup StandardString
@{

\fn int strcmp(const char *str1, const char *str2)
\brief Compares the null terminated strings str1 and str2 to each other.
\param str1 The first C string to compare
\param str2 The second C string to compare
\return The difference of the first differing pair of bytes or 0 if the strings are identical

\fn int strncmp(const char *str1, const char *str2, size_t n)
\brief Compares the null terminated strings str1 and str2 to each other for up to n bytes. Comparison ends when a null is read or when n bytes are read, whichever happens first.
\param str1 The first C string to compare
\param str2 The second C string to compare
\param n The maximum number of bytes to compare
\return The difference of the first differing pair of bytes or the final pair of bytes read or 0 if the portions of the strings read are identical

\fn char *strcpy(char *dest, const char *src)
\brief Copies the string in src into dest and null terminates dest. There should be no overlap of dest and src in memory.
\param dest The destination buffer with enough space for src
\param src The source C string
\return The destination buffer dest

\fn char *strncpy(char *dest, const char *src, size_t n)
\brief Copies up to n bytes from the string in src into dest and null terminates dest. If dest is null terminated before n bytes have been written, null bytes will continue to be written until n bytes total were written. There should be no overlap of dest and src in memory.
\param dest The destination buffer with enough space for n bytes
\param src The source string
\param n The number of bytes to copy
\return The destination buffer dest

\fn char *strcat(char *dest, const char *src)
\brief Concatenates the string in src to the end of the string pointed by dest and null terminates dest. There should be no overlap of dest and src.
\param dest The destination buffer with enough space for src beyond the null character
\param src The source C string
\return The destination buffer dest

\fn char *strncat(char *dest, const char *src, size_t n)
\brief Concatenates up to n bytes from the string in src to the end of the string pointed by dest and null terminates dest. There should be no overlap of dest and src in memeory.
\param dest The destination buffer with enough space for src beyond the null character
\param src The source string
\param n The maximum number of bytes to copy
\return The destination buffer dest

\fn size_t strlen(const char *str)
\brief Calculates the length of a null terminated string.
\param str The C string.
\return The length of the C string str.

@}

@addtogroup StandardTime
@{

\typedef time_t
time in seconds since the epoch, January 1st 1970

@}

\typedef unsigned int uint32_t
\brief 32-bit unsigned integer number

\typedef unsigned int uint16_t
\brief 16-bit unsigned integer number

@}

@defgroup Misc Miscellaneous
\brief Miscellaneous

Useful helper functionality for building your pebble application that doesn't fit in any other category.

*/

/* stdio.h */
int snprintf(char *str, size_t n, const *fmt, ...);

/* stdlib.h */
#define RAND_MAX
int rand();
void srand(unsigned int seed);
void *malloc(size_t size);
void *calloc(size_t count, size_t size);
void *realloc(void *ptr, size_t size);
void free(void *ptr);

/* string.h */
typedef unsigned int size_t;
int memcmp(const void *ptr1, const void *ptr2, size_t n);
void *memcpy(void *dest, const void *src, size_t n);
void *memmove(void *dest, const void *src, size_t n);
void *memset(void *dest, int c, size_t n);
int strcmp(const char *str1, const char *str2);
int strncmp(const char *str1, const char *str2, size_t n);
char *strcpy(char *dest, const char *src);
char *strncpy(char *dest, const char *src, size_t n);
char *strcat(char *dest, const char *src);
char *strncat(char *dest, const char *src, size_t n);
size_t strlen(const char *str);

/* locale.h */
char *setlocale(int category, char *locale);

/* time.h */
typedef unsigned int time_t;

/* C99 integer types */
typedef int int8_t;
typedef int uint8_t;
typedef int int16_t;
typedef int uint16_t;
typedef int int32_t;
typedef int uint32_t;
typedef int int64_t;
typedef int uint64_t;