Writing custom libraries for Energia (Arduino)

This is just about the pragmatics of: where do I put source files so that they are a shared library?

Custom: one you write yourself.

Library: a set of C++ source files (.h and .cpp) that you want to share among projects.

The simplified Energia/Arduino view

Outside the simplified Energia/Arduino world, libraries would be in a separate, shared directory and they would be pre-compiled into an object and separately linked into your projects.  In the Energia/Arduino world, that is all hidden.

Also, in the Energia world, a library seems to be a zipped directory of source files that follow some conventions that identify the version and documentation of the library.   So you can share the library.  I don’t know what the conventions are.  But if you are going to share your custom library, you should follow the conventions, and zip it up.  Then others can use the simplified user interface for installing zipped libraries.  Here, I don’t bother with the zipping.

Creating a custom library

Briefly, you just need to create your source files in the place that Energia looks.

Find where your sketchbook directory is:  In Energia choose “Sketch>Show Sketch Folder.”  Expect a file browser dialog (the Finder on the Mac) to show you the directory.

You will see a sub directory named “libraries”, and it will probably be empty.  (I don’t know where Energia keeps all the other pre-installed libraries.)

In that directory, create a directory with the name of your library e.g. “PWM”.

In the “PWM” directory, create your .h (and maybe .cpp) files, e.g. “pwm.h”

Now switch back to Energia and select “Sketch>Include Library>”   Expect a hierarchal menu to appear.  Expect to see “PWM” in the “Contributed libraries” section of the menu.

You can also choose “Sketch>Include Library>Manage Libraries”.  Expect a browser kind of window to open.  You should be able to browse to a line saying “PWM version unknown INSTALLED”.  (In my opinion, this should not be called “Manage Libraries” because it seems all you can do is view a list of the libraries.)

(Note that Energia expects at least one source file in your library directory.  Until then, Energia may give an error “Invalid library found in….”)

Referencing the library

In your main sketch “#include <pwm.h>”

Then define an instance of the PWM class and call its methods.

Developing and managing your library

You can just edit the files in place, using another editor.   When you use Energia to “verify” the main sketch that uses the library, it will recompile your changed library.

By managing I mean: copy the files out of the sketchbook folder to a safer, more shared place.  The sketchbook is in /Users/foo/Documents/sketchbook (on a Mac).  I prefer to put them under source control in a “git” folder, or in the “Dropbox” folder, so when I am done developing, I copy the library folder somewhere else.

I suppose you could use git in that directory, and when you are done, commit and push that repository to a your shared (master) repository on github.

Brief Summary

A library is just a named directory in the directory “sketchbook/libraries”.  You can create a library yourself using a file browser and editor.

Advertisements

0xFFFFFFFE, reclaim_reent() error symptoms of embedded programming

This is a report of one cryptic symptom (and possible) fixes you might encounter when you are embedded programming.  I report it because I have experienced it more than once and always forget what it means.

When you are trying to flash your embedded mcu,  the debugger seems to download to the chip, the debugger starts  and then stops showing a stack trace something like this:

0xFFFFFFFE
reclaim_reent()

Usually you expect the debugger to stop at main() and wait for you to tell the debugger to run (but that depends on whether you have configured your IDE and debugger to breakpoint at main.)

It might mean (not a program bug, a process error):

  • your linker script <foo>.ld describes the memory of your chip incorrectly
  • you haven’t erased the chip’s ROM yet

About the latter.  I am not sure, but modules you buy might already be flashed with a program such as a DFU bootloader, and are configured to protect a debugger from overwriting that code in ROM.  For example, on the Nordic NRF51, to remove the protection and erase all of ROM so that you can then use the debugger:

 nrfjprog --recover --family NRF51

 

 

Patching (for Linux) lib_search tool in TI’s tool chain for embedded wireless development

Context

General

Trying to use CCS Desktop on Linux or OSX to build SimpleLink example programs for TI’s embedded wireless chips such as the CC26xx family of chips.

Specific

Fixing a Windows specific tool invoked by the projects of the examples.

References

A one-year old post on TI’s forum

TI’s wiki page for Linux

TI’s wiki page for OSX

TI’s wiki on Portable Projects

Why do you need the lib_search tool?

As far as I know, certain needed code is shipped as pre-built libraries ( .a files.) The example projects are not configured to build the libraries, only to link them in.

The lib_search tool does some sort of configuration.

Aside

I don’t understand what exactly the tool does, why all the libraries are not just in some directory that the linker searches for needed unresolved symbols.

The references seem to suggest that the libraries CAN be built on the Windows platform.  That seems to imply the library source code is not proprietary, i.e. not secret, only copyrighted and licensed.  It seems like it SHOULD be possible to build the libraries on any host system.

How so ever the libraries get built, they are hardcoded for a specific target chip, and possibly for other code such as a version of TI-RTOS?  Or does it pertain more to what the app image needs from the stack image of the embedded program?

Anyway, you don’t need to understand it to patch it.

Where in the project build is the tool invoked?

The example projects are configured to use the tool as a ‘pre-build’ step.  To see that, highlight a project in the Project Explorer pane of the CCS Desktop IDE, click on it with right mouse button, and choose ‘Properties.’  Expect a dialog.  Select ‘Build’ in the left pane of the dialog.  Expect the right pane to show many tabs. Look under the ‘Steps’ tab for a ‘Pre-build steps’ section.

Symptoms of non-portable tool use

When you build on a non-Windows platform you might get:

error #10234-D: unresolved symbols remain

that is, the linker could not find said certain libraries, because the linker command file was not built by the pre-build step.  The root cause is visible much earlier in the log of the build, the pre-build step (lib_search) failed and the build process ignores the failure (proceeds to compile and link.)

The non-portable aspects of the tool

The pre-build step invokes lib_search.exe.  That is a python program (and the interpreter) that has been packaged/bundled for Windows OS (so that python does not need to be installed onto the host.)

(Strange: the BT SDK developers don’t support non-Windows platforms, but they use the tool Python which Windows OS does not support, and they used the tool py2exe so they can ship the SDK portable to any stock/virgin Windows host.)

But as of BT SDK v2, the python source is shipped with the SDK.  So on any host where python2.7 is installed (most Linux/Unix and OSX hosts), and where certain other dependencies (the python package ‘lxml’) are installed, the tool will run as interpreted python.

Old patch for the problem

Some of the references suggest installing Wine and other tools that let Windows executables run on Linux/Unix hosts.

Then the fix is (roughly speaking) prepending wine to the command:

lib_search.exe ...     =>     wine lib_search.exe....

Another patch for the problem

Here we invoke the python interpreter on the python source.

Then the patch is (roughly speaking) prepending ‘python’ to the command and changing .exe to .py:

lib_search.exe ...     =>     python lib_search.py  ....

Here, we assume  “python” invokes python2.7 (which it often does, except if you have changed it to invoke Python 3 or later.)

For this step to work, you must install the python packages that lib_search uses, and the package’s dependencies (lib_search depends on python package lxml which depends on C libraries libxml2 and libxslt.

To install those dependencies:

pip --upgrade pip
pip install wheel
pip install lxml

More exactly, in the build step change:

"${TOOLS_BLE}/lib_search/lib_search.exe"

to

python "${TOOLS_BLE}/lib_search/src/lib_search.py"

More to the patch

Define and redefine certain project path variables:

In the project’s Properties>Resources>Linked Resources>Path Variables  redefine

TOOLS_BLE  <= ${BLE_SDK_ROOT}/tools

and define

BLE_SDK_ROOT <= /home/<you>/ti/simplelink/ble_sdk_2_02_00_31

Change the .xml configuration file

(e.g. in TOOLS_BLE/lib_search/params_split_cc2640.xml)

Use a text editor to change “\” to “/” everywhere in file paths.  (Windows uses backslash in paths, other OS’s use forward slash.)

If you haven’t done this step, you see an error message that lib_search emits, saying

Cannot match   <foo> to any library .opt file in <bar>

where bar is a file path like “…./.\host….”

Setting Up a Linux Development System for Embedded Wireless using TI LaunchpadXL-CC2650 EVM

About

A record of my learning experience.  Discusses general, high-level considerations. Gathers many links that I followed.

Audience

For advanced, C programmers who are new to TI’s tool chain for programming embedded devices.

Similar documents

CC26xx Family SW Quickstart Guide also covers this material.

This blog shows a similar process for an older EVM (SensorTag), but using Windows OS and CCS Desktop.

The Narrow Subject

Here I assume the CC2650 target (an mcu and radio system on a chip) but only discuss:

  • Bluetooth (the chip allows other protocol choices i.e. WiFi or Zigbee)
  • TI-RTOS (other RTOS choices might be various free OS’s)

This might apply to other TI chips such as CC13xx, CC2640, and other earlier chips.

The Broader Subject

Wireless networks, not necessarily IoT development.  My use case is not serious IoT: I don’t want to connect to the Internet and I don’t even want to talk to standard Bluetooth devices, just between two of my own.  I don’t even want Bluetooth protocol, it just happens to be what I studied first.

Disclaimer

I could be wrong.  You should follow links to original sources.

Other target, IoT, and wireless network ecosystem choices

ARM mBed ecosystem also offers an online IDE, desktop development tools, an RTOS, and bluetooth stack.

The CC26xx target uses the ARM ISA.  You might be able to use the ARM ecosystem, but I think the bluetooth stack in the ARM ecosystem might not work on the CC26xx?  The CC26xx has two processors, a host (ARM M3) and a network (ARM M0) processor.  A Bluetooth stack should have an interface at the HAL layer between the upper layers of the BT stack and a network processor’s implementation of the lower layers.  I don’t know whether either the ARM bluetooth stack upper layers, or the TI network processor lower layers (in firmware on the M0), conform to any HAL interface standard.

(Note that TI also has much documentation on implementing “network processors”.  There, they are treating the CC26xx as a server for yet another processor, the application processor, say a powerful cpu of a desktop PC.)

ARM does not make chips (only the design IP for them).  You might consider whether using TI tools locks you into their chips, and whether using the ARM ecosystem would give you a choice of chips.

TI’s IDE Choices

CCS Cloud – “online IDE” or “online compiler”: browser and cloud based: few files stored or installed on your development system (host)

CCS Desktop – installed on your host computer, based on Eclipse IDE

Energia – (Arduino clone) does not support the CC26xx family target.

Dev System OS Choices

For CCS Cloud, shouldn’t matter, but it does: to burn to the EVM requires setting up communication via USB to the EVM, which is host OS dependent (drivers and permissions.)  CCS Cloud requires installation of TI Cloud Agent on your desktop.  All three major OS’s are supported.

For CCS Desktop, all three major OS’s are supported, but Windows seems to be favored.  E.g. installing the Bluetooth stack is biased: requires Wine on Linux.

TI’s instructions  for Building BLE Projects on Linux.  It acknowledges that TI does not officially support their BT stack on a Linux dev system (but they do support their IDE and RTOS.)

Overview

To develop, you need three components:

  • IDE (CCS Desktop or Cloud)
  • TI-RTOS
  • Bluetooth stack (or another wireless stack, i.e. library)

Using CCS Cloud, all three components come easy, automatically.

Using CCS Desktop, you must know the steps.

Installing CCS Cloud

Installation is minimal.  Search for “CCS Cloud Tools”.  Click on “CCS Cloud>Click to Start Developing”.  It will open in your browser.  When you first try to “Run” your target app, it will give you further instructions for installing:

  • a browser plugin
  • TICloudAgent

You must install TICloudAgent, and on Linux it depends on installing certain 32-bit libraries.  It’s web page seems out of date, it doesn’t show support for Ubuntu 16.4 or for this EVM (Launchpad.)

CCS Cloud is intended for starting programmers or small trials, i.e. for education and evangelism.  I don’t think the user base is large, yet.

I want to use it ( I have used Energia for small projects.)  But so far, I have had a fitful experience.  In other words, it seems somewhat fragile: requires refresh or restarting things.  Maybe slow.  But at least you can quickly experiment and learn the scope of your project (what might work, what else you need to learn.)

For example, at first ‘Run’ (burning to target) didn’t work for me, and after rebooting my dev system the next morning and plugging in the EVM after CCS Cloud was started, it did work.

For example, at first a project built successfully.  Then subsequent builds failed even though I had not changed a line of code.  The fix may be to delete a project and redownload it (using TI Resource Explorer.)  Maybe it is a consequence of changing between my two host computers.

Sometimes it fails to login (“too many logins”).  I guess there are limits on their servers?

The browser connection times out at inconvenient times (say every 30 minutes.)

Run (download to target)

“Failed to connect to target” : you don’t have the target plugged into a USB port on your desktop.

“Firmware update required” : the debugging interface half of the EVM board requires flashing.  This seems to be a warning, as download to the target seemed to proceed.

Installing CCS Desktop

Linux instructions.

A training video.

Additional notes

CCS Desktop is based on Eclipse IDE.  It is not a plugin that you can download from within Eclipse, but is downloaded and installed(?) separately (thats weird.)  If you are an Eclipse user, the overall look-and-feel is familiar, but specifics might not be.

The installer is 32-bit, but TI  says to use 64-bit Linux (that’s weird.)  You MUST follow the instructions for installing 32-bit library dependencies. (a 64-bit host will run 32-bit apps if the needed 32-bit libraries are also installed.)

The installer won’t run by double clicking it (because “>file *.run” shows it is 32-bit ELF?) but will run from the command line.  The installer is a .run instead of a .bin (thats weird?) but see this explanation of what a .run file is (essentially, an installation tool outside the approved Debian process.)

If you the installer starts but shows an error dialog “Failed to locate …libgcrypt…” you didn’t follow the instructions for installing that component.  You follow the link and click on “32-bit” (which points to ftp for a .deb file)  and expect to continue to install libgcrypt using “Ubuntu Software” installer app.

When the CCS Desktop installer runs, expect a wizard to run, that downloads and installs.

CCS Desktop: Installing TI-RTOS

You install TI-RTOS (development libraries) from within CCS.  Navigate to the TI App Center and choose “TI-RTOS for CC13xx and CC26xx”.

CCS Desktop: Installing Bluetooth Stack

TI’s instructions  for Building BLE Projects on Linux gives specifics for installing the BT stack on Linux using Wine (Windows emulator.)  Those instructions seem to be out-of-date.  I needed these changed instructions:

sudo apt-get install wine
sudo apt-get install winbind
(Download the Windows .exe installer.)
cd ~/Downloads
wine ble_cc26xx_setupwin32_2_01_00_44423.exe  (expect installer dialog)
cd ~/ti
cp -r ../.wine/drive_c/ti/simplelink/ . 

My changes to the instructions:

  1. Once you install the BLE SDK, I suppose it creates files in the proper place, and then you can uninstall Wine from your Linux computer?
  2. When I tried “>wine ble….exe”  it yielded errors about “ntlm” and needing package “winbind.”  And failed to create ~/<me>/.wine/drive_c/ti  (where it should be installing files.)  So I also installed package winbind.
  3. The installer did not seem to create .wine/drive_c/Program Files(x86\)/Texas Instruments/Boundary/  so I omitted the step of copying it.

(I haven’t successfully built a project yet.)

CCS Desktop: Importing Example Projects

I tried the TI Resource Explorer and did not have much luck finding

TI’s instructions  for Building BLE Projects on Linux also gives instructions for importing example projects.

CCS Desktop: Tweaking Example Projects

The instructions there for changing the linked resources (paths, capitalization of fileNames, and fileName wording) are slightly dated but generally accurate: you will need to use the principle and tweak the exact changes yourself.  For example, the filename “RF.c” seems to have changed in the latest release of BLE SDK.

If you get:

error: can't create session manager: can't find a JVM;
 the environment variable 'XDCTOOLS_JAVA_HOME' is set,
 but does not appear to be a directory containing a 64-bit
 Java Runtime Environment

Then see this post on TI Forum .

 

What are Images?

For the CC26xx, burning the target comprises two steps:

  • the app
  • the bluetooth stack

These are two different projects in the IDE.

TI calls them “images”.  I suppose that means they are loaded in different addresses of target ROM, and that the app on the target knows where to find the BT stack.  You only need to burn the BT stack once (unless it changes upstream, a new version.)

What are the symptoms of failing to burn both?  The app and not the BT stack:  does the app complain somehow?  The BT stack and not the app: nothing whatsoever happens, there is no app to boot?

Test Projects, CCS Cloud

How to use TI’s example projects to test your dev system.  These were written while I was using CCS Cloud; they might not apply to CCS Desktop.

Project Zero for CC2650

A demo app to burn onto your SimpleLink LaunchPad.   Essentially it sets up the Launchpad as a BT peripheral that a central device (a phone, etc.) can poll (see advertisements), connect to, and change attributes (to blink LED’s.)    This describes the demonstration, what a user sees.

As near as I can tell, this is NOT the app that is burned into a LaunchPadXL-CC2650 out of the box.  At that time, pushing the upper right button on the LaunchPad causes it to BT advertise, and for the green LED to blink.

This can be a test case for your development system.  If you successfully build and burn it, it should behave as described, talking to a BT scanner on another device.  Unfortunately, to see the results you need to use some of the free BT scanner apps, you need another BTLE enabled device, Android 4.3 or greater, or a recent iPhone or iPad that supports BT Low Energy.

 BigTime

This project prints “debug messages” once per second for a few seconds. It doesn’t use the radio.  It is intended to teach how to code semaphores etc.

CCS Cloud:  When you click the Debug icon, expect a dialog to open (the dialog that shows progress).  It should say, in order, paraphrased:

  • Building…
  • Loading…
  • Initializing…

The red/green led on the top half of the EVM should blink as the program is burned.

CCS Cloud: Then the dialog goes away and the debug panels of the IDE show new information, and a marker appears across from “main()” in the panel that shows the code.  The debugger is waiting for you to start the app.

Press the “Resume” icon in the debugger panel (looks like the standard “Play/Pause” icon on VCR’s).  Expect the program to run and print some messages into the Debug tab of the panel across the bottom of the IDE.  The final message should be “bigTime ended.”

 SimpleBLEPeripheral

This example project is configured for another EVM.  When you try to “Run” it on the LaunchpadXL-CC2650 EVM, you get the error “….Failed to connect….”.

To fix it, click right mouse button on the project in the Project Explorer Pane of CCS Cloud.  Expect a menu to pop up.  Choose “Project Properties”.   Expect a dialog to appear.  In the “General” section, in the “Connection” textbox, click.  Expect a pulldown menu to appear.  Choose “XDS110” (the type of interface on the upper half of this EVM.)  Choose OK and build again.

Repeat for the other half of the project, the …App… versus the ….Stack….

Other Notes

It seems like a few “Run” errors in red while burning, such as “Failed Device Reset”, are ~normal~ and that CCS Cloud retries and eventually succeeds.

Sometimes Ubuntu displays “You have just opened  a digital audo device” dialog meaning it has seen the Launchpad on the USB port somehow.  Choose “Do nothing” and “Do this always.”  Maybe it interferes with CCS Cloud if you don’t?

Cloud IDE for programming

About this post

The subject is software development environments that are easy to set up and use from anywhere.

This post’s quality is low:

  • written quickly
  • more questions than answers
  • from my limited experience, not exhaustive
  • it discusses programming embedded micro controllers, not programming in general

The problem

You want:

  • to minimize effort administering your development environment, and maximize time spent writing software (SetupEase)
  • to work from any physical location (Mobility)
  • to use version control (Versioning)
  • not to lose work (Backup)
  • to share (OpenSource)

Some software developers work in a single development environment in a single location.  Others may switch between many environments and many locations.  For example, software developers for embedded systems might switch environments for each brand of microprocessor they use.  They may develop at home and at work.

The State of the Art

AFAIK, there is not currently a development environment that gives you all of the above.

Solution Pieces

  • Github
  • Dropbox
  • Containers or virtual machines
  • IDE’s in the cloud

Github

Github the software provides you Versioning and Github.com the website gives you some Mobility.  But it only gives you Mobility for your source and some parts of your development environment ( such as makefiles), not for your total development environment (such as what compiler you are using.)  And the Mobility is clunky, you can’t work in your open master repository, you must work in a clone and remember to push to origin master after each work session, so that your work will be available tomorrow from another location.

Dropbox

Dropbox gives you Mobility for your source files: anywhere you work, your files will be automatically synchronized (with slight lags.)  And you can put Github clones inside Dropbox.  But you still don’t have Mobility for your complete development environment, since your IDE or compiler is installed locally, not in Dropbox.

Containers

Containers or virtual machines give you SetupEase.  Someone else can install and configure your development environment, and you download and use the whole.  For example, a development environment for open source OS Mynewt is available in a container.

But containers don’t give you Mobility.  You must set up distinct (but identical) container instances in every location.  Any files you create in a container instance, and any modifications to the development environment, are local to the container instance.   Your container could include Dropbox having a Github clone, but you still must remember to push after each session, and that might not mobilize any modifications to the environment in the container instance.

IDE’s In the Cloud

Also known as “IDE as service.”  Here, you run your development environment in a browser.  A server:

  • stores your source files
  • stores your environment
  • does all the compilation
  • runs and debugs your app (with help from an agent to the target device)

An example is Texas Instrument’s CCS Cloud.  My knowledge is limited.  AFAIK it give you SetupEase, Mobility, and Backup.  It doesn’t seem to give you Versioning and Share.  It seems to let you clone Github repositories, but not commit in the clone, or push to the origin.

TI admits in the FAQ for CCS Cloud that for advanced work you probably will need to use CCS on the desktop.  In other words, CCS Cloud is only for experimenting or trials.

CCS Cloud does let you download any files from it, so you could use a manual process in which after every session, you download, commit, and push any files you have changed in CCS Cloud to your master Github repository in Dropbox.

Other examples might be “Particle online” and “mbed online.”  (I don’t know these.)

References

EmbeddedWeekly  blogs a little about this subject.  I read that before writing this post.

 

Overview of In-App Purchase

A high-level look at IAP.  Could be wrong.  Oriented to a trial-use or freemium app.

Disambiguating

A user can acquire your app without using IAP.  That is, your app can be in the store without using IAP.

“Acquire” does not necessarily mean “pay for”.  If your app is free, a user can get it without payment, by browsing the App Store.  The free portion of your app is a product with a receipt, but it is not a product that you show in your app’s store facade, since the user already has it.

Trials

Apparently, Apple does not want “trial versions” of apps in the store.  But this just means: they don’t want duplicates (where one is crippled and the duplicate not) and  instead prefer one version with IAP.  The version in the store can still be a trial version in this sense: the app can require an IAP purchase to continue certain capabilities beyond a trial period.  Probably Apple also doesn’t want an app that won’t do anything after a trial period.  In other words, an app should continue to do something minimally useful after a trial period.

Probably they don’t even want you to advertise that an app is a trial-version: the user will see the IAP icon in the store, and know that the app may be limited (from the get-go, or after a trial period.)

Probably most users expect that certain apps will be trials or crippled.  Don’t worry about offending potential customers.

The Data Model

An app has one or more products.

A product has one or more receipts.  Each receipt is for a transaction.  (StoreKit lets you play back the transactions.)

A product has one or more content/capabilities.

Generally content/capabilities are one-to-one with receipts.

I am glossing here: it is probably only subscription type products that have many receipts for the same product.  That is, a subscription product entitles the purchaser to many contents, and each content has its own receipt.

The Facade Pattern

Your app presents a facade to the store.  In other words, your app has GUI for IAP.  Behind the scenes, your app collaborates with the store server using StoreKit.  Your app is a client of the store server.

You must submit a screen capture of your store facade during the app review process.

Validating a productID is the process for insuring that the products your facade presents to the user are indeed products in the store server (configured using iTunesConnect.)

Receipt Subclasses

Subclasses:

  • bona fide Apple receipts, stored in the app bundle and maintained by the OS/framework
  • ad hoc receipts, stored e.g. in NSUserDefaults and maintained by your app

The difference is in how much code you need, and strength of receipt against hacking.

Restoration

A purchase is restorable when a purchaser:

  • deletes your app from a device
  • buys a new device
  • enables Family Sharing for other devices

The store maintains records of purchases.   Your app must collaborate.

If you use ad-hoc receipts, when a user deletes your app, the settings for the app are deleted.  When a user re-downloads your app,  since you are not using Apple receipts, you won’t know that the user has downloaded it before (in another transaction.)  Thats a weakness of ad-hoc receipts.  Your app won’t have any record that it was downloaded previously.  Presumably, most users will purchase rather than repetitively download your free app (just to reset the trial period.)

Creating products

You need to create a product on both sides:

  • in the real store using iTunesConnect
  • in your store facade (hard coding productIDs or putting them in a .plist file)

Testing

There is a sandbox for testing IAP.  (If it works in the sandbox, it should work in the real world.  The only way to test in the real world is to actually purchase; be the first one if you are worried about it.)

Test Cases

You should test:

  1. Normal purchase: success on the main path.
    1. User declines: in your store facade, answers “No thanks.”
    2. User declines: Settings>Restrictions>IAP is On (Restrictions enabled, IAP restriction On)
    3. User declines : Cancels StoreKit’s log in dialog to the store.
    4. User declines : Cancels StoreKit’s confirmation dialog for purchase
  2. Product invalid: for some reason, what your app thinks is a product is not in the store.  (Your app configuration is wrong, or the store has removed your product.)
  3. Restoration: user installs your app on another device, or deletes and reinstalls your app.
  4. Store facade can be paused and resumed with the Home button
  5. Store facade handles user bottom double swipe up the Control Center

For a trial-use app:

  1. In the trial period: all capabilities
  2. After the trial period: capabilities are denied
  3. After the trial period: you dun the user when they try to use a capability (you present your store facade.)

Counting touches in touchesBegan() and gestures

This discusses a surprise!  something I learned the hard way.

Many touch events may come via touchesBegan() for multi-finger touches .  For example, for a three finger touch, you may get one event having one touch followed a fraction of a second later by another event having two touches, where each touch is for a different finger (having a different location.)

In other words, you can NOT rely on getting one touch event having all the touches.    You shouldn’t check Set<UITouch>.count() to determine the number of fingers the user is using.

That is the job of a gesture recognizer.  A gesture recognizer typically establishes a short window in time, and gathers all the distinctly located touches begun in that window, to determine whether the count of touches meets the requirements of the gesture.  (I presume a gesture recognizer also filters out touches that later drop out of the gesture.)

Every gesture (the superclass  UIGestureRecognizer) has the method numberOfTouches().

Many gestures can be configured with a minimum count of touches.  This is only a minimum.  A user can use more fingers and the gesture still be recognized.

  • Pan: minimumNumberOfTouches()
  • LongPress, Tap: numberOfTouchesRequired()
  • etc.

Some of the gestures also allow a maximum to be defined.

In summary: if your app supports only one finger, you might be able to use touchesBegan() and touchesEnded() to crudely determine what the user is doing.  Otherwise, you should rely on gesture recognizers to count the number of touches.

Note that certain combinations of gestures (e.g. Tap and double Tap, with a dependency defined between them) might incur a lag for gesture recognition.   In other words, using touchesBegan, you can soon determine whether a user is acting, but using gestures you might later determine a user is acting.  It can get complicated.  For example, is the  lag between start of the real gesture and when a recognizer is in the Begin state or is the lag until the the single tap recognizer is in the Finished state (which comes no sooner than the double Tap recognizer being in the Canceled state) ?