plugin-iot-rules
Architect serverless framework plugin that defines IoT Topic Rules and associated Lambdas triggered by the Rules
This plugin enables your arc.codes app to define IoT
Topic Rules
that allow your IoT Devices to trigger arc Lambda functions.
Each IoT Rule defines an event rule that triggers a custom Lambda function. The
Rule employs a SQL-like syntax to specify which messages published from your
IoT devices trigger which Lambda functions.
Installation
-
Install this plugin: npm i @copper/plugin-iot-rules
-
Then add the following line to the @plugins
pragma in your Architect project manifest (usually app.arc
):
@plugins
copper/plugin-iot-rules
-
Add a new @rules
pragma, and add any number of IoT rules by giving each a name
as the first word (the following characters are allowed in names: [a-zA-Z0-9_-]
).
This name is will form part of the name of the custom Lambda function that will be triggered
by this rule. Follow the name with a SQL query which will trigger the Lambda (see
the IoT SQL Reference). For example:
@rules
connect-device SELECT * FROM '$aws/events/presence/connected/+'
disconnect-device SELECT * FROM '$aws/events/presence/disconnected/+'
report-device-state SELECT clientid() as clientId, principal() as principalIdentifier, state.reported as state from '$aws/things/+/shadow/update'
-
Run arc create
to generate your IoT Rule Lambda functions (under
src/rules
) based on the rules you added to your app.arc
file under the @rules
pragma.
-
Edit each rule Lambda's index.js
file, just as you would any classic arc
@http
, @events
, etc. function.
Sample Application
There is a sample application located under sample-app/
. cd
into that
directory, npm install
and you can run locally via arc sandbox
or deploy to
the internet via arc deploy
.
Testing Locally
This plugin extends arc sandbox
to provide a local development experience:
- Kick up the local development environment by running the sandbox:
arc sandbox
(note the additional message logged out by Sandbox informing you of an
additional local IoT service starting up). - Load up http://localhost:3333 - the JSON array at the bottom of the page
lists out all IoT events received on the IoT Rule Topic. It should initially
be empty.
- With sandbox running, press the "i" key to trigger an IoT Rule. You will be
prompted to choose an IoT Rule (the sample app contains only a single rule),
then to enter a JSON object as a payload to deliver to the rule.
- Reload http://localhost:3333 - your JSON payload should be listed at the
bottom of the page.
Testing the Deployed Version
The sample application is ready deploy to staging via arc deploy
. Then:
- Load the URL of your deployed app; note the JSON array at the bottom of the
page and the objects it contains (if this is the first time you have
deployed, it will be empty).
- Head to the IoT Core Console's MQTT Test Page
(sometimes, soon after deployment, this test console will not be ready as a red
banner will inform you; if you find that, give it a few minutes and refresh the
page). From the IoT Core page on AWS, click the "Test" menu link on the left.
- Click "Publish to a topic."
- In the topic input field, enter 'hithere' (it should match the
FROM
clause
of the @rules
section of app.arc
). Optionally, customize the message
payload. - Load the deployed URL of the app, and a list of all messages sent to the
hithere
topic should be displayed.
Contributing
Thanks for considering contributing to this project! Check out the
contribution guidelines for details.