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
-
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).
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.
-
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
-
-
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. -
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 inus-east-1
region and you want to use git2.29.0
).
- Press Upload in the Function code block and select a copy of
-
Set environment variables
It is necessary to set at least two environment variables, otherwise the function will not succeed. These areGIT_REPO_URI
andGIT_FILE_PATH
.An example for
GIT_REPO_URI
would behttps://username:token@github.com/example/my-data.git
. The value must use HTTPS protocol and contain username and token (SSH protocol is not supported). Omittingusername
andtoken
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.
-
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 itclickTypeDouble
and paste{"clickType": "DOUBLE"}
into the event body. Such payload will simulate a double-click. -
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. -
Press the button and refresh you git repository in ≈10 seconds
-
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
-
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
-
Install dependencies using Yarn:
yarn install
-
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. -
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
-
Ensure that there are no TypeScript errors and that the code is correctly formatted:
yarn lint
-
Ensure that unit tests pass:
yarn test
The repository is continuously checked via GitHub Actions.