Futurose

Minimal FreeRTOS with Platformio

Wed, 30 Oct 2019 14:00:00 -0400

The quick start guide for FreeRTOS recommends choosing one of the working sample applications as the basis for your application. The result is that your project begins with a bunch of boilerplate code that you now own, when ideally it would all be isolated as a strict dependency.

With the dependency management and library customization features of PlatformIO, we can do better. Specifically, we can build a basic FreeRTOS application starting with just four source files.

The files are

platformio.ini - Application build and dependency specification.
main.cpp - Application code.
FreeRTOSConfig.h - FreeRTOS #define switches, some that are MCU-specific and others that are application-specific.

Can’t wait? Check out the files in my Minimal-FreeRTOS repo.

What is CMSIS?

From the CMSIS repo:

The CMSIS is a vendor-independent hardware abstraction layer for microcontrollers that are based on Arm® Cortex® processors. The CMSIS defines generic tool interfaces and enables consistent device support. It provides simple software interfaces to the processor and the peripherals, simplifying software re-use, reducing the learning curve for microcontroller developers, and reducing the time to market for new devices.

When you refer to a GPIO pin/pad by name, like PA17, a CMSIS header file is where that is defined. In addition to register access, CMSIS provides target-specific startup code, linker scripts, SysTick configuration, standard exception names, and access to special instructions. Layered on top of that core are generic peripheral drivers, as well as support for Neural Networks, DSP, standard debugging, RTOS, and Zone security.

We’re just blinking an LED, so all we need is the GPIO pin and the registers to configure it and set its value.

Minimal platformio.ini in Detail

The platformio.ini file for Minimal-FreeRTOS looks like this:

[env:feather]
platform = atmelsam
board = adafruit_feather_m0
framework = cmsis
lib_deps = https://github.com/frankleonrose/CMSIS-FreeRTOS
build_flags =
  -D CMSIS_device_header='"sam.h"'
  -D FREERTOS_HEAP_IMPLEMENTATION=1
  -D FREERTOS_MCU_FAMILY=ARM_CM0
  -D ENV_SAML21_XPRO

This file has a single build environment: feather. Every environment requires platform and board in order to build - here we are using the Adafruit Feather M0, which sports an Atmel SAMD21G18A Cortex M0+.

The file directs PlatformIO to build with the CMSIS framework. The majority of the effort making Minimal-FreeRTOS possible was adding support within PlatformIO for building the CMSIS framework with atmelsam platform.

As of 2019-10-30, this update to framework-cmsis has not been incorporated into PlatformIO. In order to use this feature, edit ~/.platformio/platforms/atmelsam/platform.json setting the framework version to the github repo: "{ packages": { "framework-cmsis": { "version": "https://github.com/frankleonrose/framework-cmsis") ...}}}.

In a PlatformIO build environment, specifying framework is optional. If you do not include a framework line, you have to provide your own startup code (the code that runs before main) and linker scripts. This can happen if you are using a library that has an embedded copy of CMSIS, as is the case using code generated by Atmel Start.

The following line starting with lib_deps lists dependencies. Minimal-FreeRTOS uses a lightly forked version the CMSIS-FreeRTOS library provided by Arm®. My version of the library includes library.json and library.py files which configure the PlatformIO build.

Lastly, there are four build flags that define macros used to select library source and include files.

CMSIS_device_header='"sam.h"' - This macro is used within the FreeRTOS header files like this: #include CMSIS_device_header and the macro value has to include surrounding quotes. Hence the double quotation of the head file name.
FREERTOS_HEAP_IMPLEMENTATION=1 - This one identifies the heap implementation among the ones provided by FreeRTOS. The options are 1 through 5, detailed here. When omitted, the value defaults to 1. If you want to provide your own heap implementation my_heap.c, simply set FREERTOS_HEAP_IMPLEMENTATION=0 (or to any number other than [12345]).
FREERTOS_MCU_FAMILY=ARM_CM0 - This one names the subdirectory of https://github.com/ARM-software/CMSIS-FreeRTOS/tree/develop/Source/portable/GCC under which to find the FreeRTOS files port.c and portmacro.h. If this flag is not specified the build will fail with an error.
ENV_SAML21_XPRO - This one is used to select board specific LED control code in this specific example main.cpp. It is not a required macro for using the CMSIS_FreeRTOS library as the other macros are.

Running on a Feather M0

git clone https://github.com/frankleonrose/Minimal-FreeRTOS
cd Minimal-FreeRTOS
Connect Feather M0 via USB and double-click reset button to enter upload mode.
pio run -t upload

Running on a SAML21 Xplained Pro

The point of limiting the number of source files is to minimize the number of things to pay attention to when making changes.

To make the simple change of board, we need to update the following files:

platformio.ini - Since the SAML21 is still a Cortex M0+, the only change to this file is to set board = saml21_xpro_b

main.cpp - The LED pad is PB10, which means we need to specify

#define LED_INIT() { REG_PORT_DIR1 |= PORT_PB10; }
#define LED_OFF() { REG_PORT_OUT1 |= PORT_PB10; }
#define LED_ON() { REG_PORT_OUT1 &= PORT_PB10; }

FreeRTOSConfig.h - No change.

Pretty simple.

Running on a 1Bitsy

Building this same blink example for the 1Bitsy board with an STM32F415RG on it takes a bit more modification.

The platformio.ini environment is slightly more verbose. The 1Bitsy requires some extra code generation flags relating to the FPU found on this Cortex-M4 chip. Also, the 1Bitsy has no built-in programmer, so it requires using the blackmagic probe as an upload tool.

[env:1bitsy_stm32f415rgt]
platform = ststm32
board = 1bitsy_stm32f415rgt
framework = cmsis
lib_deps = https://github.com/frankleonrose/CMSIS-FreeRTOS
build_flags =
  -mfloat-abi=softfp
  -mfpu=fpv4-sp-d16
  -D CMSIS_device_header='"stm32f4xx.h"'
  -D FREERTOS_HEAP_IMPLEMENTATION=1
  -D FREERTOS_MCU_FAMILY=ARM_CM4F
  -D ENV_1BITSY
upload_tool = blackmagic

main.cpp requires entirely different register manipulation to control the LED, because it is ST as opposed to Atmel.

#define LED_INIT() {                                             \
    RCC->AHB1ENR |= RCC_AHB1ENR_GPIOAEN;	/* Enable PortA clock */ \
    GPIOA->MODER |= GPIO_MODER_MODER8_0;	/* Port A.08 output */   \
  }
#define LED_OFF() { GPIOA->BSRR = (1 << 8); }
#define LED_ON() { GPIOA->BSRR = (1 << (8 + 16)); }

Conclusion

The upshot is that in order to use different boards we had to make reasonable and relevant changes. To change boards we changed a few lines in a couple files, we didn’t have to swap entire directory structures into our project. In fact, we did swap in new code, but it was well hidden within the CMSIS-FreeRTOS library where it belongs. That is a good thing and makes change and experimentation and nimbleness less costly.

Up Next

My objective is to build a standard application toolbox that I can reuse for multiple projects. I have a bunch of Adafruit Feather M0 boards, so they are going to be part of that toolbox. I want the capabilities of an RTOS to manage complexity and power consumption, so FreeRTOS is going to be part of that toolbox as well.

Blinking at the register level is all well and good to demonstrate correct builds, but to do anything serious requires more driver support. The next step will be to add a framework with drivers that makes it easier to control GPIO and DMA as well as communicate via I2C, SPI, UART, and USB, while still controlling power consumption.

Alexa Skill Architecture

Fri, 22 Jan 2016 14:00:00 -0500

##TL;DR STOP dispatching intents to a bunch of little functions each of which contains app logic, state management, and speech production. INSTEAD, structure your skill code to be easier to understand, test, and change by using a simple ‘plan’ datastructure that binds together key functions:

theplan = plan(state, intent)
state = update(state, theplan)
output = speak(theplan)

##Backstory

When I learned that Amazon was opening up Alexa to developers, I was pretty excited. I’ve been waiting for Apple to enable 3rd party development for Siri since it showed up, and there is as yet no indication that that is coming.

Of course, getting access to the docs and resources to build the skill is not the same as actually building a skill. For that, you have to offer me a t-shirt. Thankfully, Amazon did.

For my first skill, I decided to create Film Buff. The skill would allow you to ask questions like “What films star both Uma Thurman and John Travolta.” Frankly, I was amazed that I didn’t see this skill already in the gallery of third party skills. I spend 14 hours over the course of a few days putting it together thinking, wow, this is going to be very cool. Then while I’m testing with the live unit, I asked Alexa, “What film stars both Uma Thurman and John Travolta.” She answered with 3 movies. In my test code I was seeing only one answer (Pulp Fiction). WTF? Turns out, this functionality is built into Alexa already. I was asking the built in service, not my own, which would have required me to ask “Alexa, ask Film Buff what film starred…”. Doh! And this was the morning of December 18th, the stated cutoff date for getting a t-shirt.

So, back to the drawing board. I’d already invested some time in creating a skill, so ignoring the sunk cost fallacy I figured I should get something out of that. I decided to create a skill that would quiz users on U.S. State capital city names. Thus was born Capital Quiz, which Amazon certified and made live on 2015-12-29. I’ve made a few enhancements (the biggie - between-session storage of state on S3) and deployed v1.3 on 2016-01-12. As of 2016-01-21, the skill has now had 8,000+ users and caused 300k+ utterances. And I got an Alexa Dev t-shirt.

##Pervasive Skill Architecture

Amazon’s sample programs dispatch intents into separate functions, each of which takes the service request as input and returns the speechlet response. All the Alexa tutorials and and frameworks I’ve seen take this same strategy. It seems useful to do this - we have to dispatch on intent at some point - but doing it first thing spreads awareness of the form of request and response too widely in the app.

Consider what it’s going to take to test these intent functions. Each test have to provide valid input by packaging up app state and an intent into a simulated request object. In order to check correct behavior, the test code will have to unpack the speechlet response and ensure that the correct changes were made to outgoing state and that the generated speech and card are correct.

Whoa. There’s too much going on there. I’m never going to get that right. And creating a skill that supports natural seeming discourse is difficult enough already.

##The Planned Alternative

What we want is to separate decision, state change, and speech output functions so that they can be considered independently.

Here’s the primary flow of a skill that is designed with this goal:

state = recover(session, [storage], [defaultState])
thePlan = plan(state, intent)
state = update(state, thePlan)
speechlet = speak(thePlan)
if (speechlet.shouldEndSession) { storage.store(state) }
context.success(buildResponse(state, speechlet))

Things to note:

plan(state, intent) is simple to reason about because it does not generate speech. Many intents yield fixed plans like ["welcome", "prompt"] or just one of two options.
update(state, theplan) is simple because each plan operation affects state in a clear way. Many operations have no effect on state!
Using speak(theplan) isolates speech response production and inherently handles compound speech.
Lastly, update() & speak() are totally independent. In a threaded environment that could improve performance. More importantly, independent means less complex, more testable. Do I have a theme here?

##Code

Take a look at the complete working version of Film Buff here

Note on the code: It’s older style JavaScript because AWS Lambda where it’s hosted runs Node.js v0.10.36 (as of 20160122). Yes, it was a PITA to go back to all those line terminating semicolons and erase =>’s after having written and tested the code locally with a more current version of Node.js.

Further note on the code: I copied some of the basic blocks of code below and included excerpts of the test code. It looks like a lot is going on, but I’m loath to trim away the details. It’s like the problem with the Facebook view of the world - in posts it looks like everyone is having a great time and your own life looks messy in comparison. Similarly, instructional code often elides error handling and boilerplate and therefore looks simple and pure. In comparison your own working code looks overwrought and messy. But that’s often what real working code looks like. Not to suggest you shouldn’t apply any and all strategies to streamline your working code. Got it?

Full disclosure. I wrote Capital Quiz in ClojureScript wherein immutable maps and [:vectors :of [:keywords 123]] look cleaner than they do in JavaScript. (Also, since I usually consider JavaScript to be a compilation target (ever used GWT?) my JavaScript is probably really bad.) I rewrote Film Buff using the ideas from Capital Quiz in order to present these ideas without giving people paren-shock. That said, I highly recommend using ClojureScript. Every time you expand your head, it’s a good thing.

In my implementation, the state is an instance of Immutable.Map and theplan is just a JavaScript Array of operations. If an operation requires parameters, I represented it as a nested Array with the first value as the operation and subsequent values as operands.

Plan examples:

["welcome", "main-prompt"]
[["say-films", 1001, 1020, 1050], "main-prompt"]
[["say-score" game-state], "say-goodbye", "end-session"]

#Plan(state, intent) The plan() function looks like this. Note that for OneActor and TwoActors intents I call out to planning sub-functions because the logic is more than a couple lines. Even in those cases, this is the only place where slots are referenced. Could you use a more declarative system to express this dispatch table? Sure! But the important point would be to dispatch to functions that looked only at state and intent and returned a plan. Don’t do more!

function plan(state, intent) {
  switch (intent.name) {
    case "INTERNAL.Launch":
      return ["say_welcome", "prompt_two", "forget_actor"];
    case "INTERNAL.Ended":
      return ["end_session"];
    case "OneActor":
      var actor1 = intent.slots.ActorOne.value;
      return planOneActor(state, actor1);
    case "TwoActors":
      var actor1 = intent.slots.ActorOne.value;
      var actor2 = intent.slots.ActorTwo.value;
      return planTwoActors(actor1, actor2);
    case "AMAZON.HelpIntent":
      return ["say_help"];
    default:
      return [["error"], "Unknown intent '" + intent.name + "'"];
  }
}

Testing plan() looks like this:

    it('should respond to launch with welcome', function () {
      thePlan = lambda.test.plan(Immutable.Map(), {name: "INTERNAL.Launch"})
      thePlan.should.eql(["say_welcome", "prompt_two", "forget_actor"]);
    });
    it('should prompt for second when unknown actor but one stored', function () {
      thePlan = lambda.test.planOneActor(Immutable.Map({actor: UMA_ID}), 'Emily Litella')
      thePlan.should.eql(["unknown_actor", ['prompt_second', UMA_ID]]);
    });
    it('should succeed when known actors', function () {
      thePlan = lambda.test.planTwoActors('John Travolta', 'Uma Thurman')
      thePlan.should.eql([
        ['store_question', JOHN_ID, UMA_ID],
        ['answer_movies', 680], 'end_session']);
    });

#Update(state, thePlan) The update() function is as follows. State changes are no-ops or a few simple lines using only plan operands.

function update(state, thePlan) {
  return thePlan.reduce(function (s, op) {
    var opcode = getOpcode(op);
    switch (opcode) {
      case "prompt_second":
        return s.set("actor", op[1]);
      case "store_question":
        return s.update("history", Immutable.List(), function (h) {
          return h.push(Immutable.List.of(op[1], op[2]));
        });
      case "forget_actor":
      case "end_session":
        return s.delete("actor");
      default:
        // Do nothing. Most thePlan ops don't affect state
        return s;
    }
  }, state);
}

Testing update() looks like the following. In, out, simple.

  it('should set actor on prompt_second', function () {
    state = lambda.test.update(Immutable.Map(), [['prompt_second', JOHN_ID]])
    state.toJS().should.eql({actor: JOHN_ID});
  });
  it('should store question to empty history', function () {
    state = lambda.test.update(Immutable.Map(),
      [['store_question', UMA_ID, JOHN_ID], "end_session"])
    state.toJS().should.eql({history: [[UMA_ID, JOHN_ID]]});
  });
  it('should not change state with most plans', function () {
    state = lambda.test.update(Immutable.Map({actor: UMA_ID, history: Immutable.List()}),
      ["say_welcome", "say_help", "answer_movies", "neither_known", "unknown_actor", "did_not_catch",
       "unknown_movie", "same_actor", "prompt_two"])
    state.toJS().should.eql({actor: UMA_ID, history: []});
  });

#Speak(thePlan) speak() (speakOp()) is the biggest dispatcher. Keep in mind, we’re not dispatching on intents, we’re dispatching on plan operations. Again, could you put these operations into functions and use a map dispatcher? Sure! Notice that that getMoviesSpeech() is just such a call. But given that many are one-liners, it’s not entirely clear what the benefit would be. Note the critical call to combineSpeech() each time through the loop.

function speakOp(op) {
  var opcode = getOpcode(op);
  switch (opcode) {
    case "say_welcome":
      return getWelcomeSpeech();
    case "say_help":
      return getHelpSpeech();
    case "answer_movies":
      return getMoviesSpeech(op.slice(1));
    case "neither_known":
      return {output: "I don't recognize either of those actors."};
    case "unknown_actor":
      return {output: "I don't recognize that actor."};
    case "did_not_catch":
      var which = op[1]===1 ? "first" : "second";
      return {output: "I don't recognize that " + which + " actor."};
    case "unknown_movie":
      return {output: "I don't know a movie they were both in."};
    case "same_actor":
      return {output: "That's the same actor twice."};
    case "prompt_two":
      return {output: "Ask what films two actors were in."};
    case "prompt_second":
      return {output: movies.getPersonName(op[1]) + " and who else?"};
    case "end_session":
      return {shouldEndSession: true};
    default:
      // Do nothing. Often thePlan ops don't produce output.
      return null;
  }
}

function speak(thePlan) {
  return thePlan.reduce(function (speech, op) {
    var sp = speakOp(op);
    if (sp) {
      speech = combineSpeech(speech, sp);
    }
    return speech;
  }, {});
}

Testing speak() looks like the following.

  it('should end on end_session', function () {
    speechlet = lambda.test.speak(['end_session']);
    speechlet.shouldEndSession.should.eql(true);
  });
  it('should produce welcome speech', function () {
    speechlet = lambda.test.speak(['say_welcome'])
    speechlet.output.should.eql(lambda.test.getWelcomeSpeech().output);
  });
  it('should produce did_not_catch speech', function () {
    speechlet = lambda.test.speak([['did_not_catch', 1]])
    speechlet.output.should.eql("I don't recognize that first actor.");
    speechlet = lambda.test.speak([['did_not_catch', 2]])
    speechlet.output.should.eql("I don't recognize that second actor.");
  });
  it('should pronounce three+ movies', function () {
    speechlet = lambda.test.speak([['answer_movies', 680, 702, 227, 240]])
    speechlet.output.should.eql('They were in Pulp Fiction and A Streetcar Named Desire and 2 others.');
  });

##Conclusion The opportunity with Alexa is to create a lots of interesting skills. The potential for great complexity is great. Before more skills get created, we need to consider different choices for how they’re architected. I hope the strategy described here is compelling or inspires readers to consider even more alternatives.

Pro Midwife 1.3.2 for Maternity Neighborhood

Tue, 27 Oct 2015 09:00:00 -0400

Version 1.3.2 of Pro Midwife is now available on the App Store – now with support for Maternity Neighborhood. Those of you with auto-update turned on should find it already updated. When you launch the new version you will see a Welcome Back screen mentioning Maternity Neighborhood.

In addition to Maternity Neighborhood support, the new version now

Asks permission to show the badge of files to upload on the app icon
Shows a sleek progress bar while downloading clients

It’s been too long since the last update. Thank you for your patience and your continued interest in using Pro Midwife.

As always, please let me know if you have problems. And if you find the app useful, please leave a review in the App Store. Thanks!

Pro Midwife 1.2 for iOS 7

Wed, 25 Sep 2013 12:53:00 -0400

I sat down this weekend to update Pro Midwife for iOS 7. 16 hours later, it looks pretty good. I had to raise the target OS to iOS 6.0 in order to use Auto Layout. Without Auto Layout, handling iOS 7 changes would have been very labor intensive.

The Private Practice developers gave me a way to reduce the client list download size. I’m hoping that will address the most common error people encounter, which is a failure to download large client lists. That was a last minute, unexpected enhancement that went into version 1.2.0.

And, it’s up! The App went From Submission to On Sale in about 12 hours.

Pro Midwife 1.0!

Wed, 15 Aug 2012 16:08:00 -0400

I just published a new app to the iOS App Store. It’s called Pro Midwife. It’s a utility that is useful for anybody who uses the midwifery focused electronic charting software Private Practice℠. Check out the product page here.

It took 18 days to pass the app review process, including two metadata rejections. That’s only one week longer than the current average (11 days as of my submission – from reviewtimes.shinydevelopment.com). The first rejection was because the reviewer wanted a more precise explanation of how to create a test account. Rather than “Use any email address” I changed it to “Use test@futurose.com” and that was easier. The second rejection was for having a link (www.getprivatepractice.com – actually just a domain name) for Private Practice in my app description. Apple doesn’t abide by links that appear to be selling services outside of In App Purchasing. In fact, now that I think about it, it may have been the actual domain name that caused problems – that “get” at the beginning of getprivatepractice.com may have been too exhortative.

Creating subview toolbars in Interface Builder

Tue, 14 Feb 2012 16:22:00 -0500

Among other things, I’m writing an app using Xcode 4.2.1 targeting iOS 4.3. I’d like to focus on the app functionality and create a UI that behaves normally. My expectation is that tools will promote and make easy doing normal things. For example, it is exceedingly normal to use a Navigation controller and and have some views in the hierarchy show a toolbar. However, I could not figure out how I’m supposed to express this idea in Interface Builder.

Various example applications demonstrate adding toolbar buttons to the root view, which indeed works beautifully. The sample projects show a NIB object hierarchy that includes the Navigation Controller object. Within this NIB, UIBarButtonItems added under view controllers get added correctly to the toolbarItems array and they show up nicely.

But how do you define toolbar items in a NIB you have created for a subview? IB does not offer seamless support, so the solution doesn’t show up in anyone’s sample. If there is a correct way to do this in IB, I haven’t found it. In lieu of direct support, here’s my way to define a toolbar for a sub-view. It’s visual and requires only three lines of code.

In MyViewController.h:

  @property (nonatomic, retain) IBOutlet UIToolbar *toolbarPrototype;

In MyViewController.m:

  @synthesize toolbarPrototype = _toolbarPrototype;

In MyViewController.m method viewDidLoad:

  self.toolbarItems = self.toolbarPrototype.items;

Create a toolbar in the nib and add items as desired. It’s a separate top level item in the NIB, not a child of the view.
Connect the File’s Owner toolbarPrototype outlet to the toolbar item defined above

That’s it! If you’re not seeing it, make sure to set a breakpoint in viewDidLoad and poke around at the values you see.

FWIW, another way to do it that reduces the line count to 2 but increases the chance of wire up error is

In MyViewController.h:

@property (retain) IBOutletCollection(UIBarButtonItem) NSArray *toolbarItems;

In MyViewController.m:

// Relies on setToolbarItems: defined for UIViewController base class
  @dynamic toolbarItems;

Create the toolbar as above, or just create a set of UIBarButtonItems as top level NIB items.
Connect all the UIBarButtonItems, IN ORDER, to the File’s Owner toolbarItems outlet collection.

Is there a better way? Please let me know.