That said there are…. apparently…. people in this world who have a bit more resolve than I do and take their sporting and fitness activities a bit more seriously. Not only do they manage to get out of the comfy chair, they even like to measure and analyse their performance so they can improve.

Now my colleague Martin (@mdwrim) has normal furniture in his house and seems more than capable of getting out of the comfy chair and down to the climbing wall or out on his bike. He and I (@jcmrim ) talked about the kind of technology available to sporty people, in particular cyclists. Martin had just come back from watching part of the Giro d’Italia and pointed out that all the pro cyclists have sensors on their bikes. BlackBerry 10, Bluetooth Low Energy and cycling! What a perfect combination of great technology, fun and exercise as well as a great opportunity for a new Blog post, video and sample app!

If you haven’t already done so, this is probably a good time to have a read of our previous blog posts and articles on the Internet of Things and Finding Car Keys since they cover the basic concepts needed in this blog post.

As before, the first thing we did was to do a little bit of research to see if the Bluetooth SIG had defined any standards in this area; no point in re-inventing the wheel [no pun intended] and the existence of a standard would mean that a vendor may have already implemented the technology in a product.

Whenever you have a requirement that may be solvable using Bluetooth LE the first place to look is here: http://developer.bluetooth.org/gatt/Pages/default.aspx.

Browsing through the GATT Profiles we came upon this one: Cycling Speed and Cadence (CSC)… this sounded promising, and the description looked like it was just what we needed.

“The Cycling Speed and Cadence Profile is used to enable a data collection device to obtain data from a Cycling Speed and Cadence Sensor (CSC Sensor) that exposes the Cycling Speed and Cadence Service.”

The key element of this profile is the Cycling Speed and Cadence Service (UUID 0×1816) which contains four really useful fields:

• “Cumulative Wheel Revolutions”
• “Cumulative Crank Revolutions”
• “Last Wheel Event Time”
• “Last Crank Event Time”

These are part of the “CSC Measurement” GATT Characteristic (UUID 0x2A5B). They are described in detail here: CSC Characteristics and outlined in Figure 1.

There are some other characteristics that allow configuration and control of the device but we’ll talk about these when we come across them.

Figure 1 Key GATT Characteristics for CSC

So, if you think about these characteristics they allow you to derive a number of key measurements:

1. Total distance travelled – using “Cumulative Wheel Revolutions” – all you need to know is the wheel circumference to calculate this, but if you combine this with a time and a geo-location measurement you can even derive sufficient information to plot your progress on a map.
2. Speed – using “Last Wheel Event Time” – you can figure out how fast the bike is going if you do a simple calculation involving the time between successive Last Wheel Event Time values and the number of wheel revolutions that occurred in that time. But if you combine this with a geo-location measurement you can derive sufficient information to plot your speed on the map as well.
3. Instantaneous effort – using ““Last Crank Event Time”” – this can help identify those times that you’re free-wheeling and not expending energy.

It’s at this point that the engineer in me begins to wonder how to instrument a bicycle to make use of this GATT profile. Martin’s a cyclist, so, after identifying a device that matched the requirements (Wahoo Fitness Blue SC[1] device), he attached it to his cycle as shown in Figure 2.

Figure 2 Attachment of cycle monitor

For those of you who are mechanically minded small magnets on both the crank and the rear wheel spokes activate the sensor strapped to the frame. The sensor maintains the counts and timings and will report them to a suitable Bluetooth LE device such as a BlackBerry 10 smartphone.

The application that we developed based on this is actually very similar in structure to the Heart Rate Monitor application that was described in a previous blog and article. The basic logic is the same:

1. Pair the Bluetooth LE device with the BlackBerry 10 handset before using the application.
2. Launch the application which:
   1. Discovers devices that support the CSC Service (UUID 0×1816)
   2. Connects to a discovered device selected by the user
   3. Requests the device to notify our application as changes are made to the CSC Measurement characteristic (UUID 0x2A5B) which contains the wheel and crank data that we’re interested in.
   4. Receive, parse and display in numerical (RPM) and historical graphical form the CSC Measurement data as they are received.

Here are some screenshots showing what the application looks like:

Figure 3 The CscMonitor Application

Instantaneous values of the wheel and crank readings in revolutions per minute (RPM) are shown in the upper part of the screen whilst historical RPM data are plotted on the lower half of the display. Wheel and crank historical data displays can be toggled by touching the screen. Mapping RPM values to distance or energy expended would require additional information to be provided, such as the wheel circumference or radius of the crank — we’ll leave this for a possible later iteration of the application and focus on the Bluetooth LE aspects for now.

If we inspect the GATT services the CSC device supports using a tool like BTool we can see (Figure 4) that the CSC Measurement Characteristic (UUID 0x2A5B) is exposed at handle 0×0023. Handles are the references to entries in the GATT that our application will discover and use to access the value associated with a characteristic. We’ve used handles before in both our previous examples.

Figure 4 GATT showing CSC Characteristics

Associated with the CSC Measurement Characteristic is a “Client Characteristic Configuration” characteristic (UUID 0×2902) exposed at handle 0×0024. The value of this field determines whether our application will receive Notifications or Indications for the CSC Measurement Characteristic. We’ve used these before as well in our previous examples. In this case this characteristic will be set to enable Notifications using the BlackBerry 10 Bluetooth LE API.

So, how do we manage the data that is notified to us from the CSC device? The CSC data received is managed by a class called “CscDataContainer” … here’s part of its definition:

class CscDataContainer: public QObject {
       Q_OBJECT
private:
       CscDataContainer();
...
       // notification data
       QQueue<csc_notification_t> _csc_notifications;
       // CSC values
       QQueue<csc_values_t> _csc_values;
       int _min_wheel_rpm;
       int _max_wheel_rpm;
       int _avg_wheel_rpm;
       long _total_wheel_rpm;
...
}

At its core are a couple of queues that maintain the data that is received. The queue has a maximum length that can accommodate one notification per second for an 8 hour period. A future version might persist these data in a database but this is sufficient to demonstrate the principle in this case.

Once again the excellent little JavaScript library called “Flot” is used to plot these data in a WebView component in QML.

As notifications are received by our application the addNotification() method of the CscDataContainer class is called with the CSC Measurement data passed as a (uint8_t *) and a length (uint16_t) — that is an array of bytes.

Parsing this data is the first task and it’s instructive to see how this works – the main points are highlighted in the code fragment below:

void CscDataContainer::addNotification(const uint8_t *val, uint16_t len) {
       // parse value, paying attention to the bit settings in the FLAGS field
       bool wheel_revolution_data_present = false; // bit 0 of Flags field
       bool crank_revolution_data_present = false; // bit 1 of Flags field
       uint32_t cumulative_wheel_revolutions = 0;
       uint16_t cumulative_crank_revolutions = 0;
       uint16_t last_wheel_event_time = 0;
       uint16_t last_crank_event_time = 0;
       int index = 0;
       uint8_t flags = val[index];
       wheel_revolution_data_present = ((
flags & WHEEL_REVOLUTION_DATA_PRESENT) == WHEEL_REVOLUTION_DATA_PRESENT);
       crank_revolution_data_present = ((
flags & CRANK_REVOLUTION_DATA_PRESENT) == CRANK_REVOLUTION_DATA_PRESENT);
       // Fields are in the order of LSO to MSO.
       // Where LSO = Least Significant Octet and MSO = Most Significant Octet.
       index++;
       if (wheel_revolution_data_present) {
              // Cumulative Wheel Revolutions, 4 bytes.
             // Field exists if the key of bit 0 of the Flags field is set to 1.
              cumulative_wheel_revolutions =
(val[index + 3] << 24) | (val[index + 2] << 16) |
(val[index + 1] << 8)  |  val[index];
index += 4;
              // Last Wheel Event Time, 2 bytes. 
              // Field exists if the key of bit 0 of the Flags field is set to 1.
              last_wheel_event_time = (val[index + 1] << 8) | val[index];
              index += 2;
...
}
       if (crank_revolution_data_present) {
// Cumulative Crank Revolutions, 2 bytes. 
// Field exists if the key of bit 1 of the Flags field is set to 1.
              cumulative_crank_revolutions =
(val[index + 1] << 8) | val[index];
              index += 2;
              // Last Crank Event Time, 2 bytes. 
              // Field exists if the key of bit 1 of the Flags field is set to 1.
              last_crank_event_time = (val[index + 1] << 8) | val[index];
              index += 2;
    ...
    }
...
}

The first byte of data contains an 8-bit flag field (see Figure 1 for details). This indicates whether crank or wheel data is present in the following data.  If these are present they are represented in Little-endian form and need to be extracted by shifting them out a byte at a time.

The rest of the application is more focussed on the display of this data using QML so I’ll leave that for you to look at yourself since the main learning points are to do with how to interface to the Bluetooth Low Energy device itself.

We made a video which has Martin (@mdwrim) showing the application in action and explaining the code. Here it is:

If you want to know more then check out the following resources:

• The complete source code for this application on Git Hub;
  • https://github.com/blackberry/Cascades-Community-Samples
• If you’re completely new to Bluetooth LE then we recommend you read our “BlackBerry 10 Bluetooth LE Primer for Developers”  which you’ll find in our knowledge base. This and all other Bluetooth LE related developer resources that we’ve created, are listed in a single resource index page:
  • http://supportforums.blackberry.com/t5/Native-Development/BlackBerry-10-Bluetooth-LE-resource-index/ta-p/2326147

I hope you’ve enjoyed this short note and hope it has piqued your interest to find out more about Bluetooth Low Energy and how it can be integrated into your BlackBerry 10 applications.

---

[1] This should not be regarded as an endorsement by BlackBerry, explicit or implied.

http://www.webrtc.org/reference/architecture

I would like take this opportunity and introduce you to our good friends at Hookflash who have successfully ported all major components of both WebRTC and Open Peer libraries to BlackBerry 10. To provide a brief overview, WebRTC is an open source multimedia & network stack that supports real-time audio & video. The value Open Peer delivers to WebRTC applications is peer-to-peer (P2P) signalling on the wire, Instant Messaging, Federated Identities and multiple mobile platform support.

So why is this so important?  Well, it enables developers to build rich, compelling, real-time communication applications integrating Social Identities with Voice, Video and Messaging using BlackBerry 10 Native SDK. Secondly, WebRTC is free to use if you decide to commercialize your application. What Hookflash has achieved on BlackBerry 10 really exemplifies the power of our BlackBerry 10 Native Platform to deliver the best communications experience.

I would like to further highlight Hookflash team’s experience in porting both WebRTC and Open Peer stack’s over to BlackBerry 10 platform. Check out my interview with Erik Lagerway (Co-founder) & Robin Raymond (Chief Architect) from Hookflash below:

What is Hookflash?

Hookflash is a globally distributed software development team building “Open Peer”, new “open” video, voice and messaging specification and software for mobile platforms and web browsers.  Open Peer enables an important new evolution of communications; Open, for developers and customers to create with. “Over-the-top” on the Internet, where users control their economics and quality of service. “Federated Identity” so user’s connections aren’t limited by service provider’s walled gardens and operating systems. “Integrated”, as communications become a native function in software and applications. Hookflash founders, lead developers and Advisors accomplishments include; creators of the world’s most popular softphones, built audio technology acquired and used by Skype, built GIPS technology acquired and open sourced by Google to create WebRTC, and engaged in WebRTC standards development in the IETF and W3C.

What is Open Peer SDK and how would this empower BlackBerry 10 developers?

Open Peer enables direct integration of social identities, video, voice and messaging communications for developers building native BlackBerry 10 (NDK) applications. Voice, video and messaging flow Over The Top (OTT) via the Internet.

These services are delivered peer-to-peer (P2P) providing extremely strong privacy, security and encryption. Open Peer enables federated identities and allows developers to leverage and integrate whatever identity model they currently have, so their users remain their users!

What features does Open Peer SDK support?

The Open Peer SDKs are built according to the Open Peer specification. Here are a few of the features we have built into the current SDKs…

• HD real-time video
• Wideband voice and messaging
• Peer-to peer signalling & media transport (greater efficiency, reliability & privacy)
• Federated identity for cross-platform communications (not to be confused with Single Sign-On)
• Encrypted & secure communications

Would HTML5/WebWorks developers be able to leverage this in BlackBerry 10?

Yes. The current SDK is for BB10 NDK developers at this time. However, we have an active “opjs” project under development that will allow interaction between a native BB10 application and an HTML5/WebRTC enabled browser thus allowing web applications to communicate directly with native BB10 applications.

Share your experience in cross compiling your code for BlackBerry 10

Like all platforms, there’s is a learning curve relative to what you are used to until you find yourself comfortable in a new environment, and BB10/QNX is no different. The richness to the platform experience is impressive on the BB10 and made iOS feel somewhat dated by comparison.

Since QNX is a POSIX compliant system, it was relatively easy to get a majority of open source code ported to BlackBerry 10. The QNX GCC-compliant mode has helped us as well.

There were a few wrinkles along the way. The documentation and NDK felt young compared to other more established platforms but that kind of level of documentation grows out of community support and interaction.

One major difference between this project and other platforms has been the phenomenal support that Blackberry has provided us as developers, especially as Hookflash is pushing the platform and technology harder than most with real time communications in audio and video. This was refreshing, We’ve never seen such incredible support for their developer community.

Have you ported over the entire webRTC engine to BlackBerry?

Yes, we have ported all major components of webRTC library to BlackBerry. We will be extending what is offered by WebRTC’s library as well.

How long did it take to port the WebRTC and Open Peer code to Blackberry 10?

When you consider the size of the code-base that had to be moved, and the fact we had not worked on QNX /  Blackberry 10 before, it went relatively quickly. The entire move took us approximately 90 days.

Are you going to commit this work back upstream to WebRTC project?

Yes, our code will migrate back to the WebRTC project. Hookflash is extremely busy on a number of fronts making Open Peer widely available with limited resources.  We appreciate help from other developers. Pushing the WebRTC codebase back upstream will be of tremendous value to the Blackberry developer community. Requests to join our Open Peer BB10 github project are always appreciated.

What APIs did you use to build your application on BlackBerry 10?

NDK’s audio, camera and rendering subsystems and Boost are the bulk of the components. We use Cascades/QT for the sample application.

Do you have VP8 Video working on BlackBerry 10?

Yes. We had some difficulty getting the assembly to compile properly but with Blackberry’s support we were successful in porting an optimized version of VP8 to the BB10 platform. Keep in mind we have tested this mostly on Z devices at this time with limited testing done on the Q devices.

How was your experience relative to working with other platforms and BlackBerry 10?

As mentioned earlier, Blackberry feels a bit new in the documentation area and there are still a few bugs to take care of in the platform. Having said that, the platform is forward thinking, flexible and impressively powerful. Blackberry’s support has been beyond anything we could have hoped and even expected.

As more developers are drawn to the platform, documentation and community involvement will improve the access to information on the platform and increase the samples available to draw upon.

For such a new entrant into the market, our team is thoroughly impressed.

How was your experience working with the RIM team?

Bar-none, the best support we’ve ever had from a major platform vendor directly into the project. Kudos to RIM / Blackberry for providing such a spectacular community outreach.

When is Open Peer SDK going to be available for BlackBerry 10?

Our SDK is ready now in beta, developers can get it on Github today. We continue to polish this and our other toolkits, we expect commercialization to begin later this year. Follow us on github and twitter to get the latest news on Hookflash and Open Peer development.

I hope you found this interview informative and useful.  If you have any questions or feedback please leave a comment below or reach out to me directly on Twitter _GurtejSandhu. Kudos to Hookflash team for making this all happen.

So we’ve updated the socialinvocation sample to include examples of how to invoke Foursquare with all of the currently supported invocation parameters.

As you can see, Foursquare allows BlackBerry 10 developers to leverage their app in a number of different ways, both through Cards and the Invocation Framework.

Big thanks to Kyle from Foursquare who has also documented these features in his sample app:  https://github.com/foursquare/foursquare-bb10-sdk

If you want to learn more about Social Invocation and why you should be including it in your app, come to one of our sessions next week at BlackBerry Live!  We’ll be talking about the benefits of integrating with Foursquare and the rest of the Social apps in two sessions:

JAM37 - Building context-aware applications by leveraging the power of Foursquare APIs, Thursday, May 16

JAM52 - Get Social: Connecting your app to Facebook, Twitter, Foursquare, and more! Wednesday, May 15

Kyle from Foursquare will be there, and we will show a real world example of how Untappd found success by integrating with Foursquare.  Sample apps, best practices, and code snippets will also be presented that will show developers how to quickly get started in both the BlackBerry WebWorks SDK and the BlackBerry Native SDK.

Next week is BlackBerry Jam Americas 2013 and as a member of the Developer Relations team, I’ll be stationed at various locations over the three days helping out developers when I can. Better yet, i’m also hosting a lab that I hope you will find a lot of fun and very informative on stereoscopic 3D and HDMI output for your apps. I’m also presenting a session on getting the most out of Momentics to help you build and package your apps in an efficient manner and streamline your development process. This is something all developers should care about since saving time during development often means you can take on more projects and earn more in the process.

JAM54 – Lab: Adding a new Dimension to your BlackBerry Apps – Stereoscopic 3D ( and other advanced applications for output to the HDMI display)

My first experience with stereoscopic 3D, like most people, was from playing with a ViewMaster as a child. In the years since, I have experimented with stereoscopic photography, utilizing stereoscopic 3D graphics in 3D modeling and rendering software I worked on in university and during the first few years of my career, and now I am reviving some of that early work in my spare time and applying that knowledge to develop stereoscopic software for the BlackBerry 10 platform.

Stereoscopic 3D represents another way your app can engage with its users and set it apart from the competition. Imagine users playing your game on the big screen with the game play literally in their face or taking a look at NASA rover stereoscopic photos with their smartphone and feeling like they are looking out the window at the Red Planet. That’s the kind of emotion and excitement that this technology brings to those who truly appreciate it.

The techniques we will review in the lab produce stereoscopic 3D output via the HDMI display in a manner that should be compatible with the majority of 3D TVs and monitors in the market today.  The diagram below provides an overview of what type of output is generated and I will have sample code on hand so that attendees can dive right in and integrate it into their applications.

Is that all we will cover? Absolutely not. The stereoscopic techniques rely on HDMI output. HDMI output can be useful in a number of other types of apps as well. We will review some other use cases and show how the existing sample code can be adapted for those purposes. If you want to incorporate stereoscopic 3D output into your app or if you just want to know how to output content to the HDMI display in general, join in on the fun. After the lab is over, the 3D TV will be moved into the Jam Space for attendees so you will have the rest of the event to access the TV and test the changes you make to your apps and demo your efforts to others.  I’m looking forward to seeing what our developers produce with this new tool in their arsenal.

 JAM39 – Build and Packaging for native apps

As your app portfolio grows, you are probably trying to come up with ways to reuse code you wrote in a different application or organize it better, turnaround changes faster. Maybe the app’s download time is a little slow and you want to improve on it but don’t know how? If any of these questions apply to you, you want to attend this session. We will run through some tips and tricks we use for internal apps and some little known options available in the Momentics IDE to help you develop a build system to be more efficient during the development process.  We will show you some tips on how to build a Qt or Cascades shared library. If you develop on multiple platforms, we will share some tips from our porting guides on how best to create a shared pool of code that you can build on multiple platforms. If you want to use a shared library developed by someone else, we’ll show you how to integrate that library with the IDE for seamless integration with your apps.

These sessions are just the tip of the iceberg of the session catalog at this year’s conference. Join us in Orlando and learn a lot about what you can do now and what’s coming in future versions of BlackBerry 10. I am looking forward to seeing some familiar faces and to meeting more developers again this year.

Coding and deploying for the devices with 10.1 OS

Even if your older 10.0 Z10 version of the app runs “fine” on the newer 10.1 devices (Q10 and upcoming Z10 update) running the 10.1 OS version, you should try to use the latest 10.1 SDK. Why? Starting with the 10.1 SDK, you get access to some new features which will enhance your app’s experience on the Q10 devices significantly. This particular blog post here is a great source of information when you are converting your Z10 app for the upcoming Q10 devices. In terms of the UI elements that you can leverage as a developer, among others, you now have access to certain components like the auto hiding ActionBar, customizable/freeform and sticky TitleBar – these elements will allow you to maximize your screen real estate (for the smaller screen Q10 devices) and provide more room for actual content for the users.

Key shortcuts and listeners are some of the other slick new features; they make common tasks much easier for your users. The Q10 devices are definitely designed for the power users who love the physical keyboard and who value productivity greatly. You want to show them as much useful content as possible (even in the smaller screen) and require as few user input as possible to get to the primary features and content.

What about my current applications for the Z10 devices?

If there are any updates or bug fixes necessary for your currently public Z10 versions of the app (made using 10.0 SDK), you definitely don’t want to keep your users waiting. Until the in-market Z10 devices receive the 10.1 updates, you should continue posting updates and bug fixes as necessary. Going forward, the new 10.1 features that you will be using for Q10 devices (which you definitely should be) and upcoming Z10 updates; if they are mainly on the QML asset files, you can just continue to maintain just one BAR file. All the 10.1 specific QML code; those asset files can be placed in the folder called 720×720. For devices running lower 10.1 OS, that folder will just be ignored and only the QML files in the root folder would be considered. You can check out the github sample apps here to look at the code for projects like these. If you are using any new 10.1 C/C++ API then your application would need the latest 10.1.X.X SDK to compile against to bypass all the compile errors (the corresponding BAR file would also be a different one, since it would need the minimum 10.1 platform to run against).

Project Explorer View

The QML code under the 720×720 folder. It is using some new 10.1 specific features (e.g. customizable TitleBar).
If the same BAR file is run on the 10.0 devices, this code won’t be executed (the folder will be ignored).
Note: This is a modified sample code shown here just for demonstration

The QML file under the root assets folder; this will run by default. Note that there is no 10.1 specific code here

Note that you can install all the different SDK versions through the IDE update options and install the different OS versions. Re-iterating what is mentioned on the release notes:

• If you are developing using a BlackBerry 10 Dev Alpha device, you need to download the 10.0.10.263 target from the update site.
• If you are developing using the BlackBerry Z10 smartphone, you need to download a target from the update site that matches the device version that’s provided by your wireless service provider. You can verify the device version by opening the Settings app, tapping About, selecting OS in the Category drop-down list, and checking the version that’s listed in the OS Version field.
• For more information about developing apps that work on different versions of the BlackBerry 10 Native SDK, see Appropriate version of the BlackBerry Native SDK in the BlackBerry Support Community Forums.

How do I specify restrictions to BlackBerry World and BAR files?

When you are submitting the signed BAR files through your vendor portal account, you can choose the minimum OS version and the devices accordingly. These settings control whether or not your app will show up on the users’ BlackBerry World app (depending on the devices and the OS version they are currently running on).

Note that there is also a specific value that can be set through the bar-descriptor.xml file, which dictates the minimum required platform OS version required to install and run the app. This in turn gets reflected on the final signed BAR produced (MANIFEST.MF file). Do not modify this default value set unless you are absolutely certain which device OS versions you want to prevent the app from being installed (even if they are discovered through the BlackBerry World app). This value is checked by the OS itself when the app is installed and run using the BlackBerry World app. However, this is not something that the BlackBerry World looks at (currently) to filter what apps the user can see to download. This means, if you are playing around with this value, there could be instances where the user can see or buy the app through the BlackBerry World app but not be able to install it! The vendor portal filtering only gives you granularity between 10.0.0, 10.0.10 and 10.1.0 for now but if you are modifying the bar-descriptor.xml value for this, you can end up being really specific (10.0.9.X, 10.0.10.X, 10.1.X.X) which could prevent your users from installing the app (even if they are being able to see it or buy it).

The bar-descriptor.xml editor from the QNX Momentics IDE

Viewing the resulting signed BAR file through the IDE (MANIFST.MF file)

Viewing the resulting signed BAR file through the IDE (MANIFST.MF file)

Managing code base

Since there are newer API/libraries with 10.1 SDK, you might already be thinking about how to manage your code base better. Well, there are a few different options to choose from:

1. If you are already using a version control system like Github, just use the branching and merging technique for your code base
   • Create a new branch from your latest 10.0.X.X code version. Add all the new 10.1 features here and continue to use this one for devices running 10.1 (Q10 devices for now and soon to be Z10 as well)
2. If your 10.1 changes (e.g. using some of the newer UI elements and features) are mainly on the QML assets, you can make use of the static asset selector which is new with 10.1. Basically, your IDE will be pointing to the same project (code base) but based on which device you are targetting your app, it will select the respective .qml files
   • As mentioned before, the Z10 devices running lower than 10.1 OS, will just ignore the folders such as the 720×720
3. If you are using 10.1 specific API in your C++ code (only), you can use the NDK versioning macros to detect the OS versions. This forum post here talks about this in details

To Sum Up

• For devices running 10.1 OS, definitely use 10.1 SDK to compile and deploy your app; make use of all the useful features which will make the Q10 experience of your app significantly better
  • As soon as 10.1 OS is picked up by the Z10 devices, these app releases will be shown through BlackBerry World as well (provided you set the vendor portal filtering accordingly)
  • There is more than one way to manage your code base; you have to decide which one is best for you
• For posting updates and bug fixes to the 10.0 Z10 versions of your app, continue to use the respective 10.0 SDK to compile and deploy the app
• Sanity check: Don’t forget to test and try out the application on the OS versions that your users are expected to run the app

We hope at least some of this was helpful to you. If we have missed any particular cases, do bring them to our attention and we will try to advise accordingly. Hope to see all of your apps for the Q10 devices soon!

The Cascades Framework uses a modular approach to store, access, and display data in your apps.

There is a good chance you will need your app to interact with external data – the raw data for your app. The format of the external data can vary depending upon your needs and Cascades provides classes that help you manage three common data formats: XML, JSON, and SQL.

First, let’s look at a table comparing BBOS and BlackBerry 10 Data Storage:

USER File system

BlackBerry 10 introduces a file system (recall on BBOS there was no file system). So, what to know about the file system? Firstly, the working directory is where your app is started – it is also called current directory and the sandbox ($sandbox/app). Access to files and folders in the working directory is controlled through Unix-style groups and permissions. Key point: never hardcode absolute file paths – all should be relative to your sandbox.

Please review the following file system diagram:

And visit this page :

https://developer.blackberry.com/cascades/documentation/device_platform/filesystem/index.html

For more information on the file system.

Secondly, let’s look at working with XML, JSON, and SQL. The following provides some code snippets for all three along with links to more information.

XML

The following is a code snippet on how to load XML using a GroupDataModel

// Create the data model, specifying sorting keys of "firstName" and "lastName" 
GroupDataModel *model = new GroupDataModel(QStringList() << "firstName"
                                           << "lastName"); 

// Create an XmlDataAccess object and load the .xml file. The QDir::currentPath() 
// function returns the current working directory for the app. 
XmlDataAccess xda; 
QVariant list = xda.load(QDir::currentPath() + 
                         "/app/native/assets/employees.xml", 
                         "/employees/employee");

For more on XML data, please click “Working with XML”

http://developer.blackberry.com/cascades/documentation/device_platform/data_access/working_with_xml.html

JSON

The following is a code snippet on how to create a JSON Data Access Object and load the JSON file

// Create a JsonDataAccess object and load the .json file. The  
// QDir::currentPath() function returns the current working  
// directory for the app. 
JsonDataAccess jda; 
QVariant list = jda.load(QDir::currentPath() + 
                         "/app/native/assets/employees.json");

For more on JSON, please click “Working with JSON data”

http://developer.blackberry.com/cascades/documentation/device_platform/data_access/working_with_json.html

SQL

The following is a code snippet on how to create SQL

 // Create an SqlDataAccess object 
    SqlDataAccess sda(home.absoluteFilePath("mySQLFile.db")); 

    // Create a table called Employee in the database file 
    sda.execute("CREATE TABLE Employee( firstName VARCHAR(50), 
                 lastName VARCHAR(50), salary INT);"); 

    // Insert employee records into the table 
    sda.execute("INSERT INTO Employee (firstName, lastName, salary) 
                 VALUES ("Mike", "Smith", 42000);"); 
    sda.execute("INSERT INTO Employee (firstName, lastName, salary) 
                 VALUES ("Joe", "Brown", 55000);");

For more on SQL data, please click “Working with SQL”

http://developer.blackberry.com/cascades/documentation/device_platform/data_access/working_with_sql.html

In conclusion, the data files that you work with in your apps are stored in the file system on the device. Different file system locations have different permissions; in some areas, you can create new files to store your app data, while in others, you can only load data from existing files. If you want to access your data files using the method that works best for you, you need to understand where your data files are located in the file system. Please follow this link “File system access for app” for more information.

Data files that you package with your app (when you compile the app) are located in the assets folder in the file system. Your app has read-only access to this folder, which means that you can load data from files in this location, but you can’t save new data in these files. When you create new data files dynamically while your app is running, they are stored in the data folder. Your app has full read-write access to this folder, so you can load and save data using files in this location.

Now on to Part 9!!

We’ll be posting videos as part of this series leading up to BlackBerry Jam Americas in Orlando in order to give some more background surrounding the topics that we’ll be discussing in detail during the conference.

This particular video will give you some information about the upcoming roadmap items that we’re looking at for the Cascades UI Framework. In this video we’re joined by Markus Landin, all the way from Malmo Sweden, to talk to us about Cascades and the evolution of the framework on BlackBerry 10!

Last week we traveled out West to Vancouver and Saskatoon and teamed up with WaveFront to host our first ever BlackBerry Jam Starter Sessions. The aim of these Starter Sessions is to introduce the BlackBerry 10 platform to eager developers in the area, and get their hands dirty by offering hands-on labs and walkthroughs that demonstrate the ease and power of developing using WebWorks and Cascades…and to have fun while doing it!

The mornings begin with an overview of the BlackBerry 10 Development platform. How is BlackBerry 10 different from previous BlackBerry operating systems? What tools are available to develop on the platform? Why should you care about writing apps for BlackBerry 10? How do you get started? All of these questions and more are answered within the first 30 minutes of the day!

After the overview, we get into the fun stuff. The first half is all WebWorks. What support does BlackBerry offer for HTML5 development? What can you do with HTML5? What is included in the WebWorks toolkit? How do I access native APIs? By the time this presentation is over, everyone is ready to start writing…and that’s what we do! The following two hours are dedicated towards getting you acquainted with WebWorks and writing your first application for BlackBerry 10. How does it look? You’ll find out using our Ripple Emulator!

After an awesome lunch break (seriously, we had pad thai!), and an opportunity to network, we get back to it with Cascades and the C/C++ native SDK. You’re introduced to the Cascades UI framework, the various controls available to you, the abundance of APIs you can leverage, and more. We discuss how events work in Cascades, built-in behaviors of the UI, and some of the key components you’ll come to love.

Once you’re done learning, it’s time to start doing! We get your environments setup and get to building, step-by-step, your first beautiful Cascades application, and run it through the BlackBerry 10 simulator so you can interact with it.

The turnouts were great, and so were the people. I’m still receiving awesome feedback from developers that learned a ton…and who doesn’t want to be part of an end-of-day rock-paper-scissors tournament for great prizes?!

Sound like something you’re interested in? Well the Starter Sessions don’t stop in Saskatoon! We’re heading out to Montreal and Halifax April 16th and 18th to do it all over again. If you’d like to participate, hit the link below for details on location, registration, and agenda; we’d love to have you.

Starter Session Details:

http://www.wavefrontac.com/wavefront-events/vancouver-blackberry-jam-starter-session/

Ever since the launch of BlackBerry 10 on January 30th, momentum for the BlackBerry 10 platform has been explosive – BlackBerry World currently has over 100,000 apps and games and is growing every single day. Now is the time to port your existing apps and build new ones for the rapidly growing Built for BlackBerry platform.

Wavefront and BlackBerry are teaming up to present hands-on development workshops to support your app building and get you prepared to submit to BlackBerry World.

The BlackBerry Jam Starter Session will take you through the basic principles of building BlackBerry apps, with an overview of what to expect through the process. After the session, you will have the opportunity to start building your own BlackBerry apps with support from on-site BlackBerry Evangelists.

Who should attend?

• Developers with an HTML5, Cascades, Air, or Android app, who are ready to port to BlackBerry 10
• Experienced developers wanting to learn more about the BlackBerry opportunity

Why develop apps for BlackBerry?

• Increase your reach to a new audience of early adopters looking for great quality apps
• Showcase your apps that may be buried or lost in other saturated stores
• BlackBerry developers are well supported and rewarded – check it out

What to bring & prepare:

• Laptop running Windows 8, Windows 7, Windows Vista, or Mac
• Download and install the free current versions of WebWorks and Cascades developer tools ahead of time

Agenda:

08:30AM – 09:00AM – Registration and Breakfast

09:00AM – 9:30AM – Presentation Overview

09:30AM – 10:30AM – Intro to HTML5

10:30AM – 10:45AM – Coffee Break

10:45AM – 12:30AM – Hands on Lab – Getting Started with WebWorks

12:30PM – 01:30PM – Lunch

01:30PM – 02:30PM – Intro to Cascades

02:30PM – 02:45PM – Coffee Break

02:45PM – 04:30PM – Hands on Lab – Getting Stared with Cascades

04:30PM – 05:00PM – Wrap Up and Prize Draws

Fee: $25 + HST, includes breakfast, lunch and refreshments.

When:

Tuesday, April 16th, 2013

8:30am to 5:00pm

Where:

CRIM

405 Ogilvy Avenue

Suite 101

Montreal, QC, H3N 1M3

When:

Thursday, April 18th, 2013

8:30am to 5:00pm

Where:

Halifax World Trade and Convention Centre

1800 Argyle Street, Suite 101

Halifax, NS

Register now to learn how you can develop cutting edge BlackBerry apps that will increase your reach and grow your revenue.

The Cascades framework is a rich and powerful modern UI framework build on top of the Qt application framework. The UI can be developed in C/C++ or Qt Modeling Language (QML) or both.

Lets take a look at a sample HelloWorld application in both frameworks:

HelloWorld side-by-side. A label in both Java and Cascades

// MAIN: the setup
public static void main(String[] args)    
{
      HelloApp app = new HelloApp();
      app.enterEventDispatcher();

}

	// MAIN: the setup
Q_DECL_EXPORT int main
(int argc, char **argv)
{
   Application app(argc, argv);
   new HelloWorld(&app);
   return Application::exec();
}

// HELLO WORLD CLASS

public class HelloApp extends
   UiApplication {
public HelloApp () {
 HScreen scr = new HScreen();
  pushScreen( scr );
      }

	// HELLO WORLD CLASS

HelloWorld::HelloWorld 
(bb::cascades::Application *app)
: QObject(app)
{
    QmlDocument *qml = 
QmlDocument::create("asset:///main.qml")
.parent(this);

    // create root object for the UI
    AbstractPane *root = 
qml->createRootObject();
    app->setScene(root);
}

// SCREEN CLASS: THE UI

public class HScreen 
extends MainScreen {

  private LabelField lbl;
  public HScreen()
  {
    lbl = new   LabelField( "Welcome!" );

    add( lbl );

  }}	// QML Page : THE UI

Page {
    Container {
        layout: DockLayout {}
        Label {
            text: qsTr("Hello World")
}}}

Both frameworks start with the main application and the HelloWorld class. In the case of Java a screen gets pushed on the screen stack. In the case of Cascades a QML document gets associated with root UI object.

In Java, a Screen Class gets created by extending MainScreen and adding a LabelField to it. In Cascades a Page gets declared and a Label is placed inside a container as shown on the screen.

When embarking on porting any application that include the User Interface. It’s important to review the UI guidelines for both platforms.

The BlackBerry Java UI guidelines can be found at:
https://developer.blackberry.com/design/bb7/

The BlackBerry 10 UI guidelines can be found at:
https://developer.blackberry.com/design/bb10/

A note on Java UI

The BlackBerry Java Development Environment (JDE) or the Eclipse Plugin is used to develop applications for BlackBerry OS 7.1 or lower.

There are two main supported frameworks for creating user interfaces in Java:

• MIDP UI APIs
• BlackBerry UI APIs

For compliance, the MIDP APIs are included for porting apps from MIDP devices. The BlackBerry UI APIs target specifically BlackBerry development and are the main focus of this article.

Rendering in Java And Cascades UI Frameworks

In Java UI rendering is done in “widgets” using the paint() functions. Normally, a list of such “widgets” will represent your entire UI. The system will go through the entire set of “widgets” and ask them to draw themselves by calling the “paint()” method. The consequences of this implementation are as follows:

In Cascades, rendering is done differently. Unlike in Java where the application is part of the rendering loop a Cascades application only manages the UI tree. The Cascades Rendering engine (which executes on a separate thread) takes care of drawing the UI. The consequences of this implementation are as follows:

For more information on the topic please see this blog post.

(http://devblog.blackberry.com/2012/09/cascades-custom-ui/)

Navigation:

Single Screen

Normally a single screen Java application would extend from MainScreen as in the HelloWorld sample provided. Similarly in Cascades a Page would get created with individual components added to it.

Screen	Page

Stack of Screens

In traditional Java applications flow is maintained by adding and removing screens to/from the stack, which is owned by the main application. The equivalent to this on BlackBerry 10 is the Navigation pane where individual pages can be pushed and popped from a stack. For more information on Cascades Navigation Pane please see: http://developer.blackberry.com/cascades/reference/bb__cascades__navigationpane.html

Tabs and Filtering content

In Java applications Tabs are used to display filtered content and are achieved with the PaneManagerModel. This can be achieved in Cascades using Segmented Control.

Cascades tabs allow the apps to change the flow of the application. In BlackBerry Java, this effect was achieved through the use of custom components.

PaneManagerModel, Pane, HorizontalTabTitleView, PaneView, PaneManagerView	SegmentedControl http://developer.blackberry.com/cascades /reference/bb__cascades__segmentedcontrol.html
Custom Component implementing custom Toolbarhttp://docs.blackberry.com/en/developers/ deliverables/17965/Toolbars_6_0_1137042_11.jsp	Tabbed Panehttp://developer.blackberry.com/cascades /reference/bb__cascades__tabbedpane.html

Layout

Java:

http://btsc.webapps.blackberry.com/btsc/fetch/2000/348583/800332/800505/800508/How_To_-_Create_tabbed_view_screens.html?nodeid=1357482&vernum=0

Cascades:

http://developer.blackberry.com/cascades/reference/user_interface_layouts.html

The following tables illustrate layout mapping of the most frequently used layouts.

In BlackBerry Java, the most common approach is to use combination of HorizontalFieldManager and VerticalFieldManager. This can be achieved in Cascades using the DockLayout.

FlowFieldManager	Stack Layout default behavior

Combination of Horizontal and Vertical Field Managers	Dock Layout

AbsoluteLayout

Menus:

The Java Menus documentation can be referenced at:

http://developer.blackberry.com/java/documentation/menu_items_1970228_11.html

The Cascades Menus can be reference at:

http://developer.blackberry.com/cascades/documentation/ui/navigation/menus.html

The most common way of interacting with content in BlackBerry Java was through the BlackBerry Menu (the hardware key). On BlackBerry 10, Cascades applications would use an action in the action menu to get the equivalent functionality.

BlackBerry Key Menu vs. BlackBerry 10 Action Menu

Menu (Screenshot)	ActionSet

Application “Settings” Menu. [BlackBerry 10 Only]

A swipe-down menu is accessible on BlackBerry 10 for infrequently used actions such as settings, getting customer information, managing accounts or downloads etc…

N/A	Menu class and ActionItem object

Context Menu

Context menu is a common BlackBerry specific method of acting upon an item in a specific context. This can be achieved on both platforms as illustrated below.

Context Menu	contextActions

Custom Menu

In certain cases you might want to create a completely custom menu that makes sense for your application. This is possible in BlackBerry 10 using the MenuManager API.

Override keyDown and then create a custom component to display on the screen.	MenuManager

Active Home Screen Elements

In BlackBerry Java, apps would normally change the icons and the icon descriptions to keep track of the application state. For more information on the APIs please see:

http://www.blackberry.com/developers/docs/7.1.0api/

In BlackBerry 10, apps would use Active Frames to update the status of an application. For more information of Active Frames please see:

http://developer.blackberry.com/cascades/documentation/ui/active_frames/index.html

Active Home Screen App Elements

Active Icons	Active Frames

Notifications

To learn more about BlackBerry 7 notifications please see:

https://developer.blackberry.com/java/documentation/message_list_1984778_11.html

To learn more about BlackBerry 10 hub notifications please see:

https://developer.blackberry.com/cascades/documentation/device_comm/notifications/index.html

MessageList	Hub Notifications

Popup Dialogs

DialogFieldManager and PopupManager	NotificationDialog

Custom Controls

In BlackBerry Java, custom controls are challenging to implement and often involve overriding the paint() method of native components. For more information and samples please see:

https://developer.blackberry.com/java/documentation/
advanced_ui_components_and_managers_1970227_11.html

In Cascades, custom controls are created by combining existing components and modifying their behavior. For more information on how to create a custom control in Cascades, please see:

http://developer.blackberry.com/cascades/documentation/
dev/integrating_cpp_qml/custom_control_tutorial.html

Sample Use of Custom Components	Custom Control

Dialog Boxes, Prompts, Toasts

The BlackBerry Java platform supports Dialogs of different format (information, status, inquiry). For information on dialog boxes please see:

http://developer.blackberry.com/java/documentation/dialog_boxes_1970203_11.html

Cascades supports dialog boxes, prompts and toasts. For more information on how to implement them please see:

http://developer.blackberry.com/cascades/documentation/ui/dialogs_toasts/index.html

Dialog Class	Dialog, SystemDialog, SystemListDialog … Below is an example of a custom dialog box.

Lists

For reference of List implementations in Java please see:

http://developer.blackberry.com/java/documentation/lists_and_tables_1970216_11.html

For list implementation in Cascades please see:

http://developer.blackberry.com/cascades/documentation/ui/lists/

Active Home Screen App Elements

SimpleList, RichList, TableView	ListView

Text

For reference on how to handle text in Cascades please see:

http://developer.blackberry.com/cascades/documentation/ui/text/index.html

Label

Labelhttp://developer.blackberry.com/java/ documentation/text_field_label_1984828_11.html	Label

Text Field

LabelField, RitchTextField, BasicEditField, PasswordEditField, EmailAddressEditField, KeywordFilterField, AutoTextEditField	TextField with TextFieldInputMode Of type: Default, Text, EmailAddress, Password, Chat, Url, PhoneNumber, NumbersAndPunctuation,NumericPassword, Pin

Text Area

RitchTextField and ActiveRitchTextField	TextArea with TextAreaInputMode of type: Default, Text, Chat, EmailAddress

Web Content

WebView

BrowserField http://www.blackberry.com/developers/ docs/7.1.0api/net/rim/device/api/ browser/field2/BrowserField.html BrowserField BrowserField browserField = new BrowserField(); screen.add( browserField ); browserField.requestContent ( "http://blackberry.com" );	WebView http://developer.blackberry.com/ cascades/reference/bb__cascades __webview.html WebView { id: webView url: " http://blackberry.com " }