# [Free] Background Fall & Impact Detection Extension (BgAction)
background fall detection extension for MIT App Inventor 2 (AI2).
---
### Overview
A high-performance, battery-optimized background fall detection extension for MIT App Inventor 2 (AI2). This extension leverages an Android Foreground Service and Broadcasters to continuously track hardware sensors (`ACCELEROMETER` and `GYROSCOPE`) even when the app is running in the background, minimized, or when the screen is locked.
Instead of passing heavy data strings, this extension returns **lightweight integer status codes** to maximize data processing efficiency inside AI2 block workflows.
---
## 
Extension Metadata
* **Package Name:** `com.luckyh9h.bgaction`
* **Class Name:** `BgAction`
* **Version:** `8`
* **Component Category:** Extension (Non-visible component)
* **Design Icon:** `aiwebres/icon64.png`
---
## 
Manifest Specifications
The extension handles necessary components automatically through code annotations. When your app is compiled, the following permissions and configurations are injected into the `AndroidManifest.xml`:
### Required Permissions
* `android.permission.FOREGROUND_SERVICE`
* `android.permission.POST_NOTIFICATIONS`
### Internal Android Component Registrations
```xml
<service
android:name="com.luckyh9h.bgaction.BgAction\\$FallSensorService"
android:enabled="true"
android:exported="false" />
<receiver
android:name="com.luckyh9h.bgaction.BgAction\\$FallBroadcastReceiver"
android:enabled="true"
android:exported="false">
<intent-filter>
<action android:name="com.luckyh9h.bgaction.ACTION_FREE_FALL" />
<action android:name="com.luckyh9h.bgaction.ACTION_PHONE_DROPPED" />
</intent-filter>
```
---
## 
Status Codes Definitions
To ensure high performance inside App Inventor, state changes are passed as simple numerical evaluations. Use standard comparison blocks to manage your logic pathways.
| Code | Label Constant | Event Category | Trigger Condition & Description |
| :---: | :--- | :--- | :--- |
| **`10`** | `FREE_FALL_LINEAR` | Free-Fall | Pure vertical descent. Total acceleration force falls below $2.0\text{ m/s}^2$ without major rolling. |
| **`11`** | `FREE_FALL_ROTATING` | Free-Fall | Airborne tumbling descent. Total acceleration force drops low while rotational speed exceeds $5.0\text{ rad/s}$. |
| **`20`** | `IMPACT_NORMAL` | Impact | Normal surface landing or minor bump ($35.0 < \text{G-Force} \le 65.0$). |
| **`21`** | `IMPACT_TUMBLING` | Impact | Ground strike followed by immediate bouncing or continuous rolling ($\text{Rotation} > 6.0\text{ rad/s}$). |
| **`22`** | `IMPACT_CRITICAL` | Impact | High-impact deceleration emergency. G-Force spike exceeds $65.0$. |
---
## 
Blocks Documentation
### Properties
#### 
IsActive (Read-Only)
* **Description:** Returns the active lifecycle status of the underlying background sensor listener service.
* **Return Type:** `Boolean` (`True` / `False`)
### Functions
#### 
StartBackgroundService
* **Description:** Spawns the persistent Android Foreground Service, hooks up high-frequency sensor pipelines, displays the persistent utility drawer notification banner, and dynamically registers explicit application-bound broad receivers.
* **Parameters:** None
#### StopBackgroundService
* **Description:** Safely unbinds all active gyroscope and accelerometer listeners, shuts down the system foreground notification channel context, and releases broad resources to minimize device battery consumption.
* **Parameters:** None
#### FireTestSignal
* **Description:** A safety test suite designed to evaluate backend logic frameworks inside your workspace app without having to drop or damage physical test devices.
* **Parameters:**
* `testImpact` (*Number*): Mock impact force measurement value forwarded to the receiver logic.
* `testRotation` (*Number*): Mock rotation speed value forwarded to the receiver logic.
* `testCode` (*Number*): Targeted mockup evaluation code. Inputting `10` or `11` instantly executes the `OnFreeFallDetected` event line; inputting `20`, `21`, or `22` executes the `OnPhoneDropped` event line.
### Events
#### 
OnFreeFallDetected
* **Description:** Triggers instantly the moment the phone hardware senses an ongoing weightless free-fall state mid-air.
* **Parameters:**
* `statusCode` (*Number*): Returns `10` (Linear Fall) or `11` (Rotating Fall).
#### OnPhoneDropped
* **Description:** Triggers immediately upon landing impact following an airborne free-fall state window.
* **Parameters:**
* `impactForce` (*Number*): The calculated total G-Force metric vector tracked on touchdown impact.
* `rotationSpeed` (*Number*): The maximum angular velocity magnitude calculated during the event timeline.
* `statusCode` (*Number*): Returns `20` (Normal Impact), `21` (Tumbling Impact), or `22` (Critical Impact).
---
## 
Practical Integration Workflows
Follow these integration architectures to get started with the extension:
1. **Handle Runtime Target Requirements:** For devices running Android 13 (API level 33) or higher, make sure your app logic requests the `POST_NOTIFICATIONS` runtime permission explicitly before executing the plugin.
2. **Boot Service Pipelines:** Use a core UI action block sequence (e.g., `Screen1.Initialize` or a master service controller switch) to trigger `BgAction.StartBackgroundService`.
3. **Build Fall Logic Trees:**
* Hook up the `OnFreeFallDetected` block to perform pre-impact optimizations, safe write operational saves, or initialize immediate short-range tracking variables.
* Hook up the `OnPhoneDropped` block to screen for target values like `statusCode = 22` (Critical Impact). Route these directly into automated SOS workflows, such as sending emergency SMS updates with GPS coordinates, or triggering an internal alarm sequence.
---
## 
Downloads & Releases
Get the latest pre-compiled binaries to integrate into your project or test directly on your device:
* **[ Download Extension (.aix)]( BgAction/BgAction.aix at main · seekhope886/BgAction · GitHub )**
* **[
Download Test App (.apk)]( BgAction/bgaction_ext.aia at main · seekhope886/BgAction · GitHub )**
---
## 
License
This extension project is distributed and licensed under the terms of the standard [MIT License](LICENSE).