Architecture

acoupi is designed with the primary goal of simplifying the creation of smart bioacoustic sensors on edge devices. We aim to provide a user-friendly framework that allows you to focus on defining your program's behaviour—specifying which models to execute, recording triggers, etc.—without being burdened by the intricacies of program execution and task orchestration. To achieve this, acoupi is made of two parts:

• Program Specification: This part focuses on empowering users to specify their desired program behaviour with minimal input.
• System: This part handles the execution and management of your defined program.

In the following sections, we'll provide a high-level overview of each part before delving deeper into their respective functionalities and implementation details.

Program Specification

In acoupi, a "program" encompasses the complete behaviour of a deployed bioacoustic sensor, including recording triggers, AI models used, data storage and communication protocols, and more. To strike a balance between ease of use and flexibility, acoupi offers multiple tiers for specifying your desired program, catering to varying levels of customisation and complexity.

What is a Program?

For more details on what a program is in the context of acoupi, read the Programs Section.

Ideally, most users should be able to achieve their goals by simply modifying a high-level configuration layer. However, for technically oriented users, acoupi provides the ability to customise every aspect of the sensor program while still benefiting from the underlying management layer.

Methods of Program Specification

For ease of use, acoupi offers pre-built programs that can be configured to meet specific user requirements. This approach is ideal for users who want to replicate established monitoring protocols with minor adjustments to accommodate their setup.

However, in cases where creating a new program from scratch is necessary, acoupi provides several tools to simplify this process:

• Program Templates: When you primarily need to change the AI model or make minor modifications while retaining most of the default behaviour, program templates offer a quick and easy way to create a new program.

• Task Templates: acoupi programs consist of various tasks, such as recording, messaging, and file management. Task templates provide a streamlined approach to create these common tasks with customisable sections, further simplifying program development.

• Pre-defined Components: acoupi offers a collection of pre-defined components that provide specific functionalities, such as sending messages to a server or recording audio. These components are designed for easy integration into program tasks.

• Custom Components: For scenarios requiring more specialised behaviour, acoupi enables the creation of custom components through templates or interfaces. These ensure seamless integration with the rest of the program while providing the flexibility to tailor functionality to your exact needs.

Program Configuration

To enhance the reusability of created programs, acoupi promotes easy configurability. When creating a program, users are encouraged to specify a configuration schema, which outlines all configurable parameters. To streamline this process and ensure that provided configurations adhere to the schema, we leverage Pydantic. This guarantees that program users can confidently provide configurations that align with the program creator's intentions.

Data Standardisation

To ensure consistency and facilitate data flow between components and tasks, acoupi uses clearly defined data structures for commonly handled bioacoustic sensor data, such as "Recording" and "Detection". This standardisation improves program clarity and understanding, promoting a more uniform and predictable data handling process throughout.

Example of a simplified acoupi program. An acoupi program illustrating some of the most important data schema, components, and tasks.

System

The acoupi System is responsible for executing and managing user-defined programs. It facilitates user interaction to specify program selection, configuration, and deployment. Additionally, it handles configuration and program file management, ensuring the program's state remains healthy and operational. The system also guarantees robust and timely execution of program tasks.

Key functionalities include:

• Command-Line Interface (CLI): acoupi provides a CLI enabling users to instruct acoupi to execute specific programs, modify configurations, check device status, and most importantly, initiate and terminate device deployments.

• Management: acoupi tracks the running program, its configurations, and execution logs. This enables observation of sensor functionality and facilitates error tracking.

• Orchestration: acoupi leverages Celery, an orchestration framework, to execute all tasks concurrently and in a fault-tolerant manner. This ensures efficient and reliable program operation.

The series of steps required to start an acoupi application.To have an acoupi application running on a device, three steps are required: (1) Installation of the acoupi package, (2) User configuration of an acoupi program, (3) Start of a deployment.

Our tools

To prioritise robustness and reliability, acoupi leverages a selection of established tools and frameworks, entrusting complex functionalities to battle-tested solutions. The acoupi package is built upon a foundation of other Python packages. The most crucial packages and their functions are summarised below. For detailed information about each package, please refer to their respective documentation.

• uv: Manages package dependencies and the development process.
• Pydantic: Handles data validation and schema enforcement.
• Pytest: Serves as the testing framework for ensuring code quality and correctness.
• Pony-ORM: Simplifies database queries and interactions.
• Celery: Manages the processing and orchestration of tasks.
• Jinja: Facilitates text templating for generating dynamic content.