AWS IoT Button logger to git

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.

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

   • Using a pre-built version from GitHub
     Download https://github.com/kachkaev/aws-iot-button-logger-to-git/releases/latest/download/lambda.zip

   • Using your own build from source

     git clone https://github.com/kachkaev/aws-iot-button-logger-to-git.git
     cd aws-iot-button-logger-to-git
     
     yarn install
     yarn build
     
     ## lambda.zip will appear in the project folder

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.