Pear force one

Picture this highly original screenplay.

It's the glamorous closing ceremony of The London Patriot Games 2012, and to the horror of all lucky ticket holders who managed to avoid the preliminary heats of race walking, the sum of all fears has materialised.  The pearesidential, armoured space hopper codenamed red rabbit has gone missing, and under clear and present danger, an executive order has been broadcast out on the widely muted Slack channel #yetanotherworldcrisis. To begin the hunt for its precious cargo with the ominous NATO call-sign: red movember.  Worst of all, Harrison Ford (or a slightly less effective Ben Affleck) is nowhere to be seen to save the world (again) from a certain James Cameron-scale disaster... due to prior filming commitments.  It might even have been for Titanic II: Just The Tip of the Iceberg.

Not good.  Not good at all.

Or to quote a line from Tom Clancy's yet to be released novel about a crack team of six rainbow-coloured, juiced-up fruits that rescue careless heads of state with brute, disproportionate force: everything has gone - quite literally - pear-shaped.

Yes, that's an affirmative.  Without the illustrious leadership of the very important pearson, the world is at a complete loss. There's going to be a world war, nuclear winter, zombie apocalypse, global market crash (another one) and a notable lack of chicken dishes being served at the local Nando's branch in Bristol... and that's all before the long awaited arrival of the Bank Holiday weekend.  To compound the issue further, a new season of Love Island is about to conclude, so all this mess really should have been avoided in the first place.

In other words, our right honourable friends in government should have put a plan and a system in place to avoid this grave situation even before it happened.

And that's ultimately why we're taking a leaf out of Mr. Collins' book, and following this piece of pearfect advice:

I can feel it coming in the pear tonight, oh lord
And I've been waiting for this moment for all my life, oh lord

That's right.  We're using a pear strapped to a GPS tracker to demonstrate how Tom Clancy's novels could actually have been a page-long infographic on how entirely predicable global crises were avoided without drama, with the right monitoring and preparation.

Alpha team, GO!

A surprising number of words in the English dictionary can have this four-letter word disguised within them.  There is therefore an acute danger that readers of this post will suffer from mild migraine, heart palpitations and disorientation from the sheer volume of substandard, pear-related gags that inevitably appear from this point onwards.  Starting with...

Prepear for Pearfection:

First things first.  Very important pears need to be tracked using a V.I.P. GPS receiver.  FACT.  Didn't anyone teach you this back in Beverley Hills C.S.I. Police Academy?  True; we've been tracking inherently inanimate household objects for the past 6 months.  Like empty Flora tubs.  So you rightly ask, what's new, commander-in-chef?

Well - here - we're trying to demonstrate how we might proactively raise (and react to) suspicions we might have about our things not working properly.  Or not at all, in fact.  Or starting to exhibit non-fruit-like behaviour.  Like going on a run in the local park at 2am in the morning. 

Oh. We've already reached the laggy kit selection screen, with the overdramatic score forewarning us of an imminent mission.  Quick!  This is what we'll equip our inexplicably angry protagonist with.

• We've made a completely arbitrary executive decision.  It's shamelessly peartisan.  And our support base love it.  We're ditching Flora.  Instead, we're going to use a margarine brand that is far more presidential.  Because it's literally called President.  And we'll use it to store our electronic parts.
• An ESP32 development board running MicroPython makes a speedy return to the heart of chaos like a wholly unnecessary Bourne sequel.  We're going to continue to use a Semtech SX1276 LoRa transceiver and antenna for the transmission of the pear's current GPS coordinates, which means we'll resort to using a HelTec Automation Wireless Stick Lite.
• Here's an official secret from the super secure archives of her majesty's government.  If you need to track the whereabouts of something, using a system of satellites in the sky that are designed to provide a bit of global positioning, well, you'll most likely require a GPS receiver.  And this is why we're attaching a U-blox Neo-6 based GPS receiver module (with 2-pin UART interface) to our development board.  Are we all set to press the blue × button on our gamepad?
• Not quite.  The pear.  Don't forget the pear. Otherwise all these puns were for nothing.

Here's an interim product design, courtesy of our unpaid, live-in, junior product designer who appears to have plenty of time on her hands during the summer holiday season.  Coming to an Apple store near you.

Ate-y Pear-y:

Snow White allegedly ate a poisoned organic apple well past its sell-by date and ended up quite ill.  Thankfully, we haven't.  And that means we have somehow managed to muddle our way through to the 10th instalment in our rapidly depressurising cabin that is the I-O-Tea series.  Besides, we've decided to use a different fruit for this experiment.  So all is (apparently) good.

Of all the sorties that we've undertaken to date, Soreen seems to be the hardest word prepared us best for this mission.  After all, it was the excursion in which we tracked an empty Flora tub around desolate, post-apocalyptic landscapes.  Like the South of England. Or even, Lisbon.

Here's the full potted history:

1. Frozen Pi
2. Have-ocado
3. Green, green grass of /home
4. Quantitative wheezing
5. LoRa-Wan Kenobi
6. Soreen seems to be the hardest word
7. Ironed curtains
8. 20th entry fox
9. Hard grapht

..And here's a pretty map of Lisbon with some blue dots superimposed, just to prove that our LoRaWAN / GPS combo is capable of doing something.

Pearental guidance:

What's this?  We owe the good helpless citizens a plan?

Here's our proposed itinerary.

• We use MicroPython.  And we've been using the micropyGPS library to parse GPS data successfully from our U-blox module for many months now.  So, we're going to do more of the same.  After all, this is how our pear will continue to geolocate itself amidst the severe turbulence.  This is a completely made-up IoT use case for modern day pear farmers.  No, really.
• LoRaWAN packets were also sent trundling through the airwaves using a Semtech SX1276 transceiver and our uLoRa MicroPython fork. You might remember that this particular geeky obsession started back in LoRa-Wan Kenobi.  We'll use this method (again) to send out the pear's GPS coordinates back to The Things Network, and then to AWS IoT Core.  So far, nothing new.
• But we - here at the unofficial official home of Rosie - are all about the cutting (h)edge.  AWS IoT Events was made generally available by the Amazonian Web Service back in May 2019 - and it's a product that appears to trim away at the cumbersome shrubbery that is IoT device state monitoring.  Let's use it!
• ...And this is why, once we finally get going after all this highly distracting rambling, we end up spending a majority of our time defining inputs in IoT Events, creating a detector model, and doing a bit of pointy-pointy-click-click action in a browser of our choice to create a fully representative model.  In it, we define our states, under what conditions our things move between these states, and what events get triggered as a result. 
• We'll use our detector model to see if we can send our Pear Force One command centre an ever-reliable snail mail (read receipt optional), and update the tracker's Shadow document with its current status.  All while the device transitions itself between responding, not responding and lost states.  Ultimately, this will allow a hastily assembled elite team of foul-mouthed, morally questionable, semi-retired special forces veterans to retrieve the distress messages on their ancient Blackberry BYOD devices (while perched drunkenly on a bar stool mid-morning), and promptly commandeer a hand glider to storm the margarine tub*.

*Perhaps this proposed Van Damme film plot line requires a little rework.

Now, su to froot:

Right. So we know what you are all thinking.  We've tracked objects before using the magic of GPS and LoRaWAN.  Why bother doing this again?  Good question.

It's actually because we're generally happy bunnies when everything is working just fine.  When measurements are flowing in.  When we have a nice little graph or spreadsheet showing the latest GPS coordinates of an arbitrary household grocery purchase that we can amaze our neighbours with, over a summer barbecue. But it's all a bit annoying when things have actually stopped working.  And we were oblivious to the mishap.

Take this example from Hard grapht.  When we weren't checking, there was a period in which the microprocessor had encountered a software issue, and had stopped sending measurements to our AWS IoT Greengrass device.  Wouldn't it be nice if the lack of data was somehow detected automatically?  And if we could get it to do something as a result?

Of course, we could painstakingly build a separate application to check if there has been any data received recently.  But we already promised you some AWS IoT Events pointy-pointy-click-click action to achieve this with minimal effort.

Which is why we're going on a pear hunt, with the help of AWS IoT Events.

We're going on a pear hunt. We're going to catch a big one. What a beautiful day! We're not scared. Uh-uh! A bug! A hideous, fatal MicroPython bug (of our own making)! We can't go over it. We can't go under it. Oh no! We've got to find a way to monitor it! Pointy-click! Pointy-click! Pointy-click!

Pear programming:

Let's GO, GO, GO!

But hang on a second.  What's this bold orange button labelled "Create detector model" doing in the middle of the AWS IoT Events landing page?  Sounds kinda advanced, and awfully important?  Should we hit it?  Should we, readers?

Of course, we should!  Otherwise we'd just be staring at this screen, like, forever.  And that doesn't make a good blog post.

As far as we can tell, detector models are used to define the possible states of our things, how they enter in to and exit out from those states, and what actions should be taken when they do.  Our model itself will go on to take input from AWS IoT Core messages (payload), and therefore from LoRaWAN and The Things Network further upstream.  But IoT Events works strangely independently of any other platform once it has received an input via the AWS IoT Core to IoT Events integration by a Rule.  Perhaps that is the point.  That it is an impartial observer of the going-ons.

OK, so we're fairly sure there will be no ready-made detector model templates for our exceptionally bizarre use case.  So we're going alone, solo - by creating our very own (new) detector model.

Click!

What we next encounter is an unexpectedly austere screen, consisting of some Salvador Dalí-esque circles and rectangles.  All of which can be dragged around the canvass to our heart's content.  This is great!  There is no longer any need for enterprises to enter into a licensing agreement with Microsoft for that boxes and circles program, otherwise known as Visio.

Drag-drag-click-click!

OK.  We get it.  We know how this works.  Easy! We just kinda create stuff, annotate them, and move them around the screen and draw random lines in-between, right?  Well, if so, here's our masterpiece (although we cheated by using Paint to touch it up).  Our submission to next year's Turner Prize, entitled: Insurmountably Dodgy IoT. 

Which is right on point, since The Constant Gardner's Magic Quadrant™™™™™ squarely puts Rosie the Red Robot as an unassailable market leader in the provision of IDIoT solutions.

OK.  So it transpires, this is NOT how it works.

We ought to have read the AWS IoT Events documentation.  Because it tells us that there's actually a little more to it than us randomly moving shapes around.  Let's start again.

Firstly, like anything vaguely IoT, there needs to be some sort of representation of a thing, or in this instance, an input.  Here, we'll create a simple input (representing our flying pear) and upload a JSON file that describes the data that AWS IoT Events will eventually receive from this V.I.P. via AWS IoT Core.

Here's a pretty amateurish JSON file hand-crafted to resemble the minimum amount of information we need to know about Pear Force One. We're not even sure that we will need longitude or latitude data for our purposes even, but let's stick with them for now.

{
 "device_id": "pear-force-one",
 "location": {
  "latitude": 38.8977,
  "longitude": -77.0365
 }
}

The input definition most definitely doesn't need to contain every single attribute of this thing under the sun (and the actual values supplied are ignored).  After all, for the purposes of AWS IoT Events, it only needs the attributes required for the purposes of working out its states, and actions.  If - for example - we are attempting to detect whether the device has suddenly plummeted in elevation, then we would want to ingest also the altitude attribute.

It's automatically identified some attributes from the JSON file.  Good.  Let's proceed.

Select 'em all (the attributes that is).  And we'll hopefully create this input once and for all.

Later, when we configure AWS IoT Events as a destination in an AWS IoT Core Rule, we target this input so the message is mapped.

What we configure next is the detector model, and this requires a bit of brain exercise.

Here's a few thoughts on how this might work:

• When Pear Force One sends us measurements, everything is fine and dandy.   Let's say that at this joyous moment, it's in a "responding" state.  Whenever we enter this "responding" state (or return to it), we'll send ourselves a polite and complimentary email using AWS Simple Email Service (SES), and update the thing's Shadow document in AWS IoT Core with its status.  Both of these things we'll do using a single Lambda function.  We'll also start a "not-responding" timer here.  Tick-tock.  Tick-tock.  Tick-tock.  If a new payload is received, we'll simply reset this counter.  Everything is still OK.  However, if the "not-responding" timer times out, then we transition our device into the "not-responding" state.  Things are getting a little hairy.
• If there have been no measurements for the past X minutes or hours, something's not quite right.  But it's probably too early to give Harrison Ford a call using the super presidential red phone which hasn't seen much investment since the 60s.  Let's change the state of the thing to "not-responding" though, and still do the Lambda thing and send out an email notification and perform the Shadow document update.  This way, if Accenture were to come in and do an audit afterwards, we can claim to have alerted some people of the impending doom.  Yep, we'll be squeaky clean.  If, however, data is received again during this "not-responding" state, things are of course all good again.  Hooray!  Which means it should go back to the "responding" state.  Of course, whenever entering the "not-responding" state we should start the "lost" timer.  And if we don't hear from our thing for the next X minutes or hours...
• Node Code Red!  Node Code Red!  This supremely important asset is likely to have been lost.  We'll do the obligatory email notification dispatch and Shadow document update out of courtesy... but we ought to be doing a whole load of other stuff now to make the world good again.  No need for timers here... we just keep the thing in this "lost" state.  Although if data is received again, we'll take it back into the "responding" state.

That's a lot to take in.  Just to help you regain your breath, here's an artistic interpretation of Mickey Mouse in AWS IoT Events, with a subtle help from Paint.

Back to serious business...because there was something about stuff being in peril, and lost...

Incidentally, there is a "device heartbeat" example from AWS that achieves a similar result, but we have beefed it up with an additional state and Lambda functions.  Still, it is well worth a read.

Now that we've thought about it, all this can be reflected in a fully fledged detector model, using a combination of states, events and transition events.  And because events can have conditional logic attached to them as well, and associated actions, the model can become a sophisticated web (quite literally on screen) of the thing's entire lifespan.

There are also ways to set variables internally within AWS IoT Events too, which allow us to do things like set dynamic thresholds.  For example, has the altitude of Pear Force One dropped more than 5% since the last reading?  Has its GPS coordinates stopped changing by X amount (i.e. stopped moving)?  And besides invoking Lambda functions, there are other types of actions that can be taken, like republish to another IoT topic, send to Simple Queue Service (SQS), Simple Notification Service (SNS), A-Team-as-a-Service (ATS), etc, etc, etc...

Here we go.  We're going to point, click and bash our keyboard like an IoT ninja. This is the before shot.  Look how unfulfilled this little model is before the sponsored makeover.  Not a happy model. It didn't even have an Instagram page back then.

But after a while, we end up with this lively, confident model.  The visualisation is really kinda useful, because we can physically observe what possible states our thing can find itself in, and the relationships between them.  Hmm. Maybe that was the point of all these graphics, after all. *Smart light-bulb moment*

As we enter into each one of our states, we have an accompanying Lambda function.  These do our polite emailing, and Shadow document updates.

One curious find is that when messages arrive from AWS IoT Core into IoT Events, it has been transformed with lots of additional IoT Events-specific attributes.  For example, just to get to our "device-id" in the original payload,  we had to use event["payload"]["detector"]["keyValue"] in Lambda.  Quite a mouthful, indeed.  This is where the simple action to republish as a MQTT message to IoT Core comes in handy, for troubleshooting purposes.  By monitoring on a test topic that we dispatch our payload back to, we can see exactly what attributes are being handled in AWS IoT Events.  You'll be surprised.

When we're ready for the red carpet premier, we can publish the model.

Now that the model is published, we can test this with inputs. There's a handy "sample data" feature in AWS IoT Events that allows us to simulate data as if it arrived from elsewhere.

And there we go!  As and when we decide to send our test data, and depending on which state the device is in at the time, we receive expected email notifications informing us of a change in the state.  We're using a 1 minute timeout just to speed up testing.  Clearly, in real life, we'd want ample timeout to ensure we are not overwhelmed by false positives.

Lastly, looking at the device's Shadow document, we can see that its status attribute is changing accordingly as well.  This is useful information to query if we had an additional application (like a visualisation tool or trackmypearforceonetoday web site) which simply shows us the current status of the device.

The only thing left now is to create the Rule in AWS IoT Core, which effectively sends the data it receives from a device on to AWS IoT Events as an input.

We're all set, and everything appears to be working as expected in testing.

Now, the correct course of action would be unleash this rig out in the wild where we have open The Things Network LoRaWAN gateway coverage.  But if we're feeling a little drained from all this frantic event management, we can simply capture the raw packet in bytes that our Semtech transceiver has sent, and simulate this exact uplink from our device in the TTN console.  All from the comfort of our home.

Which - rather predictably - all ends with us confirming that the payload makes its way all the way through to AWS IoT Events, resulting in our rather amusing Gmail inbox.

We are not embarrassed to admit (well, we sort of are), that it was not until some time after publishing this blog post that we realised that current states of detectors can be observed in real-time on the detector model main screen.  Which is kind of useful.

What?! We haven't yet finished our popcorn, but the credits are already rolling?  And the end credits, and the accompanying, never-ending playlist by X Factor finalists from 5 years ago, appear to be longer than the actual 62-minute running time of this straight-to-video thriller.

But that's OK.  We have demonstrated that the world doesn't always have to end up on a knife-edge, teetering on the edge of jeopardy.  With a bit of proactive monitoring and good old fashioned planning, we can be ready for some eventualities, and invoke a preprepared action plan.

Moreover, we're feeling a little peckish.  Well, how very convenient.  There's a delicious looking fruit located right beside our laptop.  We're sorry to report that our little V.I.P. has pearished.

Thankfully, a single update to our Lambda function takes care of this event.

Peartinent links:

AWS IoT Events documentation can be found here.  This is the stuff that we should all be reading.

• https://docs.aws.amazon.com/iotevents/latest/developerguide/what-is-iotevents.html

The "Device Heartbeat" example demonstrates a similar use case:

• https://docs.aws.amazon.com/iotevents/latest/developerguide/iotevents-examples-dhb.html

The micropyGPS library is being used to parse GPS data from our U-blox module in MicroPython:

• https://github.com/inmcm/micropyGPS 

We have a uLoRa MicroPython fork that we have been using for a while.  It's for sending data via LoRaWAN to the nearest The Things Network gateway.

• https://github.com/fantasticdonkey/uLoRa