Skip to content

Latest commit

 

History

History
184 lines (128 loc) · 8.08 KB

README.md

File metadata and controls

184 lines (128 loc) · 8.08 KB
Raw

AWS IoT Button logger to git

License: MIT GitHub Workflow Status (checks) Known vulnerabilities Code style: Prettier

This repository contains a Lambda function that can be triggered by an AWS IoT Button to log clicks in a chosen git repository. Doing so is useful when you want to record arbitrary infrequent events and then analyze them.

The function can be triggered by any Lambda event, such as from AWS 1-Click IoT devices or Alexa Smart Home.

Process diagram: trigger (e.g. AWS IoT Button) starts this Lambda function and passes clickTypes. The function clones a git repository to obtain files, adds a line to a file, commits and pushes back to the repository

Example output (e.g. clicks.txt in https://github.com/example/my-data.git):

2019-01-20 11:48:42 +0000 SINGLE
2019-01-31 00:42:41 +0000 DOUBLE
2019-01-31 00:43:02 +0000 LONG
2019-02-15 09:10:24 +0000 SINGLE

Caveats

  • Due to the nature of AWS Lambda and git, writing to a repository requires its shallow cloning on every function invocation. The whole process takes a few seconds, which limits the frequency of events you can log. If you trigger the function too often, git conflicts may emerge when pushing, so some events may fail to appear in your log file.

  • Batteries in AWS IoT buttons last for ≈1,000–2,000 presses and are not officially replaceable. You can still use this Lambda function if you intend to log more events, just consider using other triggers (e.g. Alexa Smart Home).

  • The git repository you are writing to cannot be blank and requires to have at least one commit on the branch of your choice (main by default).

Configuration

The function is configured via environment variables, which define the target repository as well as the format of the created log. See src/config.ts for the list of options.

Deployment

  1. Obtain the archive with the lambda function

  2. Create a new Lambda function on AWS
    See official documentation. You should end up on the function’s configuration page at the end of this step.

  3. Upload function code and configure its execution

    • Press Upload in the Function code block and select a copy of lambda.zip on you computer.
    • Set Runtime to Node 14.x and Basic settings → Timeout to 15 sec.
    • Press Add a layer and provide ARN from Git Lambda Layer repo (e.g. arn:aws:lambda:us-east-1:553035198032:layer:git-lambda2:8 if your function is in us-east-1 region and you want to use git 2.29.0).

  4. Set environment variables
    It is necessary to set at least two environment variables, otherwise the function will not succeed. These are GIT_REPO_URI and GIT_FILE_PATH.

    An example for GIT_REPO_URI would be https://username:token@github.com/example/my-data.git. The value must use HTTPS protocol and contain username and token (SSH protocol is not supported). Omitting username and token from the URL will make it impossible for the function to push the changes back to the source repository. Token generation process will vary based on where your repository is hosted (e.g. see docs for Github and GitLab). Make sure you give your new token write permissions to the repository of your choice.

    GIT_FILE_PATH must contain a relative path to the log file you want to populate, e.g. path/to/clicks.txt. The file and the containing folder do not need to exist beforehand.

    Although other environment variables are not required, there exist quite a few of them to let you customize what the function does. For example, you can configure the format of the timestamps and bring your own labels. So your output file can look like this:

    ## my-data.csv
2019/01/20,11:48:42,my custom event 1 (clicked)
2019/01/31,00:42:41,my custom event 2 (double-clicked)
2019/01/31,00:43:02,my custom event 3 (long-clicked)
2019/02/15,09:10:24,my custom event 1 (clicked)

    Details are in src/config.ts.

  5. Save the changes you’ve made to your function
    Press Save in the top right corner function’s page and wait for the zip archive to upload. You can now run your function by pressing Test next to Save. Using this button for the first time will prompt you to configure a test event. For example, you can name it clickTypeDouble and paste {"clickType": "DOUBLE"} into the event body. Such payload will simulate a double-click.

  6. Link your IoT button or another AWS IoT device to the function
    Follow the instructions for your device to link it with AWS. You can start by clicking Add Triggers → AWS IoT section in the top-left corner of your function’s configuration page.

  7. Press the button and refresh you git repository in ≈10 seconds

  8. 🎉

Development

Getting started

  1. Ensure you have the latest git, Node.js and Yarn installed:

    git --version
## ≥ 2.3

node --version
## ≥ v10.21.0

yarn --version
## ≥ 1.21.1

  2. Clone the repository:

    cd PATH/TO/MISC/PROJECTS
git clone https://github.com/kachkaev/aws-iot-button-logger-to-git.git
cd aws-iot-button-logger-to-git

  3. Install dependencies using Yarn:

    yarn install

Simulating the function locally

  1. Create a file called .env in the root of the project and define the configuration there:

    GIT_REPO_URI=https://username:token@github.com/example/my-data.git
GIT_FILE_PATH=clicks.txt

    You can add a number of other configuration options; see src/config.ts for a full list of what is available. In addition to those, you can also set CLICK_TYPE (= SINGLE, DOUBLE, LONG) to simulate different button click types.

  2. Once .env file is configured, you can trigger the function:

    yarn simulate

Alternatively, you can define the configuration inline, which makes .env unnecessary. Please note that the below syntax will not work in cmd.exe and PowerShell on Windows.

GIT_REPO_URI=https://username:token@github.com/example/my-data.git \
  GIT_FILE_PATH=clicks.txt \
  SOME_OTHER_OPTION=value \
  yarn simulate

Quality checking

  1. Ensure that there are no TypeScript errors and that the code is correctly formatted:

    yarn lint

  2. Ensure that unit tests pass:

    yarn test

The repository is continuously checked via GitHub Actions.