pebble/devsite/source/_posts/2015-12-02-Bringing-the-Family-Back-Together.md

title	author	tags	banner
Bringing the Family Back Together - 3.x on Aplite is Almost Here!	chrislewis	Freshly Baked	/images/blog/3.x-on-tintin.png

The time has almost come for Pebble Classic and Pebble Steel to get firmware 3.x!

This is great news for users who get access to all the improvements and fixes since 2.x, as well as new features such as timeline, Quiet Time, no more eight app limit, Standby Mode, and last but not least one new color (gray)!

But let us not forget about Basalt and Chalk app developers, who also have a lot to get excited about - a huge new user base of Aplite watch wearers!

This blog post aims to help developers using SDK 2.x features and APIs to migrate their apps to a single 3.x codebase. As well as bringing compatibility to all older watches when they upgrade to firmware 3.x, these changes will also serve to remove a lot of complex and ugly conditional code that has needed to exist in the meantime. Let's fix some apps!

Get the Beta SDK

To try out the beta SDK, read the instructions on the SDK Beta page.

Mandatory Changes

To be compatible with users who update their Pebble Classic or Pebble Steel to firmware 3.x the following important changes MUST be made:

• If you are adding support for Aplite, add aplite to your targetPlatforms array in appinfo.json, or tick the 'Build Aplite' box in 'Settings' on CloudPebble.

• Recompile your app with at least Pebble SDK 3.8 (coming soon!). The 3.x on Aplite files will reside in /aplite/ instead of the .pbw root folder. Frankenpbws are not encouraged - a 2.x compatible release can be uploaded separately (see Appstore Changes).

• Update any old practices such as direct struct member access. An example is shown below:

  // 2.x - don't do this!
  GRect bitmap_bounds = s_bitmap->bounds;
  
  // 3.x - please do this!
  GRect bitmap_bounds = gbitmap_get_bounds(s_bitmap);
  

• If your app uses either the Dictation or Smartstrap APIs, you must check that any code dependent on these hardware features fails gracefully when they are not available. This should be done by checking for NULL or appropriate enum values returned from affected API calls. An example is shown below:

  if(smartstrap_subscribe(handlers) != SmartstrapResultNotPresent) {
    // OK to use Smartstrap API!
  } else {
    // Not available, handle gracefully
    text_layer_set_text(s_text_layer, "Smartstrap not available!");
  }
  
  DictationSession *session = dictation_session_create(size, callback, context);
  if(session) {
    // OK to use Dictation API!
  } else {
    // Not available, handle gracefully
    text_layer_set_text(s_text_layer, "Dictation not available!");
  }
  

Appstore Changes

To handle the transition as users update their Aplite to firmware 3.x (or choose not to), the appstore will include the following changes:

• You can now have multiple published releases. When you publish a new release, it doesn’t unpublish the previous one. You can still manually unpublish releases whenever they want.

• The appstore will provide the most recently compatible release of an app to users. This means that if you publish a new release that has 3.x Aplite support, the newest published release that supports 2.x Aplite will be provided to users on 2.x Aplite.

• There will be a fourth Asset Collection type that you can create: Legacy Aplite. Apps that have different UI designs between 2.x and 3.x on Aplite should use the Legacy Aplite asset collection for their 2.x assets.

Suggested Changes

To fully migrate to SDK 3.x, we also suggest you make these non-essential changes:

• Remove any code conditionally compiled with PBL_SDK_2 defines. It will no longer be compiled at all.

• Ensure that any use of app_message_inbox_size_maximum() and app_message_outbox_size_maximum() does not cause your app to run out of memory. These calls now create AppMessage buffers of 8k size by default. Aplite apps limited to 24k of RAM will quickly run out if they use much more memory.

• Colors not available on the black and white Aplite display will be silently displayed as the closet match (black, gray, or white). We recommend checking every instance of a GColorto ensure each is the correct one.

• In addition to the point above, investigate how the contrast and readability of your app can be improved by making use of gray (either GColorLightGray or GColorDarkGray). Examples of this can be seen in the system UI in the banner at the top of this blog post.

• Apps using image resources should take advantage of the new bitmap resource type, which optimizes image files for you. Read the Unifying Bitmap Resources blog post to learn more.

Questions?

That's it! It will be quite straightforward to update most of your apps, but if you do have any problems or queries, feel free to contact us or find us on [Discord]({{ site.links.discord_invite }}).