chuckcharlie/awspaghetti repository overview

⁠3D Print Monitor with AWS Bedrock, Discord, and MQTT

This application monitors 3D prints in real-time by capturing frames from an RTSP stream, analyzing them using AWS Bedrock's AI capabilities, and sending notifications through Discord and MQTT. It's designed to detect print failures (like spaghetti) and provide immediate alerts through your preferred notification channels.

⁠Prerequisites

• Docker and Docker Compose installed
• AWS credentials file
• RTSP stream URL
• Discord webhook URL (optional)
• MQTT broker (optional)

⁠Setup

1. Ensure you have the necessary AWS credentials file and RTSP stream URL.

2. Configure the application using the docker-compose.yml file.

⁠Running the Application

1. Build and start the container:

docker compose up -d

1. View logs:

docker compose logs -f

1. Stop the application:

docker compose down

⁠Features

• Captures frames from RTSP stream every 10 seconds
• Analyzes images using AWS Bedrock
• Sends formatted results to Discord webhook
• Automatic error handling and retries
• Containerized for easy deployment

⁠Configuration

The application can be configured using environment variables in the docker-compose.yml file:

⁠Optional Features

⁠Discord Integration

To enable Discord notifications, set the DISCORD_WEBHOOK_URL environment variable in your docker-compose.yml:

environment:
  - DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-url

If this variable is not set, the application will skip sending notifications to Discord.

⁠MQTT Integration

When MQTT is configured, the application will publish status updates to the specified topic. Each message is a JSON object with the following structure:

{
    "timestamp": "2024-05-16T17:34:42.123456",
    "print_failed": true,
    "description": "Print failure was detected in the image."
}

The status is published every time a frame is analyzed, regardless of whether a Discord notification is sent. This allows other systems to monitor the print status in real-time.

⁠Volume Mounting

The AWS credentials file is mounted into the Docker container as a read-only file. This is done by specifying the path to the credentials file on the host and the path inside the container where it will be mounted. The :ro suffix ensures that the file is mounted as read-only.

⁠Cost Optimization

The ANALYSIS_INTERVAL variable can be used to optimize AWS costs. For example:

• Setting ANALYSIS_INTERVAL=30 will reduce AWS Bedrock API calls by 66%
• Setting ANALYSIS_INTERVAL=60 will reduce AWS Bedrock API calls by 83%

Choose an interval that balances your need for timely failure detection with your AWS cost requirements.

⁠Test Mode

When TEST_MODE is set to true, the application will not automatically process frames. Instead, it will wait for a manual trigger. You can trigger the workflow manually using the following one-liner:

docker exec -it rtsp-bedrock-discord python -c "from app import process_frame; process_frame()"

⁠Verbose Logging

Set VERBOSE_LOGGING to true in the docker-compose.yml file to enable detailed logging. This will output additional information about the application's operations, such as frame capture, image encoding, and analysis results.

⁠Generating AWS Credentials with write-temp-creds.sh

You can generate the credentials file using the provided write-temp-creds.sh script. This script fetches temporary credentials for a given AWS profile (using tools like aws-vault and pass) and writes them to the specified output directory in the required format.

⁠Usage

./write-temp-creds.sh <profile-name>

This will create or update your credentials file with a section for the specified profile. You can then mount this file into the container and select the profile using the APP_AWS_PROFILE environment variable as described above.

For more information on aws-vault, visit the official documentation⁠.

⁠AWS Credentials and Profile Selection

This application uses AWS credentials from a mounted credentials file (e.g., /creds/credentials). You can specify multiple profiles in this file, similar to the standard AWS credentials format:

[default]
aws_access_key_id=AKIAXXXXXXXXXXXXXXXX
aws_secret_access_key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
aws_session_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

[vault-user]
aws_access_key_id=AKIAYYYYYYYYYYYYYYYY
aws_secret_access_key=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
aws_session_token=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

(You can generate this file using the write-temp-creds.sh script as described above.)

⁠Selecting a Profile

To select which profile to use, set the APP_AWS_PROFILE environment variable in your docker-compose.yml:

environment:
  - APP_AWS_PROFILE=vault-user

Important:

• Do not set the AWS_PROFILE environment variable. If you do, boto3/botocore will try to load the profile from the default AWS credentials/config location (e.g., ~/.aws/credentials), not from your mounted file. This will cause errors if the profile does not exist there.
• The application reads the APP_AWS_PROFILE variable and selects the correct profile from your mounted credentials file internally.

⁠Summary

• Use APP_AWS_PROFILE to select the profile from your mounted credentials file.
• Do not use AWS_PROFILE in the environment.
• The app will use the credentials from the selected profile for all AWS operations.

⁠AWS Role Assumption

The application uses AWS credentials to assume a role specified by AWS_ROLE_ARN. This role must have the necessary permissions to access AWS Bedrock and perform the required operations.

⁠Required Permissions

The assumed role should have the following permissions:

• bedrock:InvokeModel: To invoke the AWS Bedrock model for image analysis.
• sts:AssumeRole: To allow the application to assume the specified role.

⁠Example Permissions

⁠User Permissions

The user running the application should have the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::your-account-id:role/your-role-name"
        }
    ]
}

⁠Role Permissions

The role to be assumed should have the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "bedrock:InvokeModel",
            "Resource": "arn:aws:bedrock:us-west-2:your-account-id:inference-profile/your-profile"
        }
    ]
}

⁠Trust Policy

The trust policy for the role should allow the user to assume the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::your-account-id:user/your-user-name"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

⁠Workflow

1. User Credentials: The application uses the AWS credentials of the user running the application to authenticate with AWS.

2. Role Assumption: The application assumes the role specified by AWS_ROLE_ARN using the AWS Security Token Service (STS). This allows the application to perform actions as if it were the assumed role.

3. Access AWS Bedrock: With the assumed role, the application can access AWS Bedrock to analyze images and detect print failures.

For more information on AWS IAM roles and permissions, visit the AWS IAM documentation⁠.