Initial commit

2025-08-17 18:51:29 +10:00
parent 214d7f8228
commit 02380cd0d9
12 changed files with 1877 additions and 1 deletions
--- a/Usage.md
+++ b/Usage.md
@@ -0,0 +1,303 @@
+# MedMate - Medicine Tracker for Home Assistant
+
+A comprehensive custom integration to track medicines, dosing schedules, inventory, and prescriptions in Home Assistant.
+
+## Features
+
+- **Complete Medicine Management**: Track active ingredients, strength, and pack sizes
+- **Flexible Scheduling**: Set doses by days of the week and times of day (morning, lunchtime, dinner, night, custom)
+- **Inventory Tracking**: Monitor pill counts with automatic updates when doses are taken
+- **Prescription Management**: Track issue dates, expiry dates, doctor info, repeats, and automatic expiration
+- **Smart Notifications**: Binary sensors for dose due, low inventory, and prescription status
+- **Easy Actions**: Buttons to take doses and fill prescriptions
+- **UI Configuration**: Complete setup and management through Home Assistant UI
+
+## Installation
+
+### Method 1: Manual Installation
+
+1. Create a `medmate` folder in your `custom_components` directory:
+   ```
+   config/
+   └── custom_components/
+       └── medmate/
+           ├── __init__.py
+           ├── const.py
+           ├── config_flow.py
+           ├── coordinator.py
+           ├── sensor.py
+           ├── binary_sensor.py
+           ├── button.py
+           ├── manifest.json
+           ├── strings.json
+           └── services.yaml
+   ```
+
+2. Copy all the provided files into the `medmate` folder
+3. Restart Home Assistant
+4. Go to **Settings > Devices & Services > Add Integration**
+5. Search for "MedMate" and click to add
+
+### Method 2: HACS (if you publish to HACS)
+
+1. Open HACS in Home Assistant
+2. Go to Integrations
+3. Click the three dots menu and select "Custom repositories"
+4. Add your repository URL
+5. Install MedMate
+6. Restart Home Assistant
+
+## Configuration
+
+### Adding a New Medicine
+
+1. Go to **Settings > Devices & Services**
+2. Click **Add Integration** and search for "MedMate"
+3. Follow the setup wizard:
+
+#### Step 1: Medicine Information
+- **Medicine Name**: Unique name for the medicine
+- **Active Ingredient**: The active pharmaceutical ingredient
+- **Strength**: Dosage strength (e.g., "500mg", "10mg/5ml")
+- **Pack Size**: Number of pills/doses per pack
+
+#### Step 2: Dosing Schedule
+- **Days of the Week**: Select which days you take this medicine
+- **Times of Day**: Choose from:
+  - Morning (8:00 AM)
+  - Lunchtime (12:00 PM)
+  - Dinner (6:00 PM)
+  - Night (10:00 PM)
+  - Custom (configurable)
+
+#### Step 3: Prescription Details
+- **Issue Date**: When the prescription was issued
+- **Expiry Date**: When the prescription expires
+- **Doctor**: Prescribing doctor (optional)
+- **Total Repeats**: Total number of repeats on prescription
+- **Repeats Left**: Current repeats remaining
+
+### Modifying Medicine Settings
+
+1. Go to **Settings > Devices & Services > MedMate**
+2. Click on the medicine device
+3. Click **Configure** to modify any settings
+
+## Entities Created
+
+For each medicine, MedMate creates the following entities:
+
+### Sensors
+- **`sensor.medmate_[medicine]_inventory`**: Current pill count
+- **`sensor.medmate_[medicine]_repeats_left`**: Prescription repeats remaining
+- **`sensor.medmate_[medicine]_next_dose`**: Timestamp of next scheduled dose
+
+### Binary Sensors
+- **`binary_sensor.medmate_[medicine]_dose_due`**: True when dose is due (within 30 minutes of scheduled time)
+- **`binary_sensor.medmate_[medicine]_prescription_active`**: True when prescription is valid and has repeats
+- **`binary_sensor.medmate_[medicine]_low_inventory`**: True when inventory is below 7 pills
+
+### Buttons
+- **`button.medmate_[medicine]_fill_prescription`**: Fill prescription (add pack size to inventory, reduce repeats by 1)
+- **`button.medmate_[medicine]_take_[time]_dose`**: Take dose buttons for each scheduled time
+
+## Services
+
+MedMate provides several services for automation:
+
+### `medmate.take_dose`
+Record that a dose was taken.
+
+```yaml
+service: medmate.take_dose
+target:
+  entity_id: button.medmate_aspirin_take_morning_dose
+data:
+  time_slot: morning
+```
+
+### `medmate.fill_prescription`
+Fill a prescription.
+
+```yaml
+service: medmate.fill_prescription
+target:
+  entity_id: button.medmate_aspirin_fill_prescription
+```
+
+### `medmate.update_inventory`
+Manually update inventory count.
+
+```yaml
+service: medmate.update_inventory
+target:
+  entity_id: sensor.medmate_aspirin_inventory
+data:
+  inventory: 25
+```
+
+### `medmate.update_repeats`
+Manually update repeats left.
+
+```yaml
+service: medmate.update_repeats
+target:
+  entity_id: sensor.medmate_aspirin_repeats_left
+data:
+  repeats_left: 3
+```
+
+## Automation Examples
+
+### Dose Reminder
+```yaml
+automation:
+  - alias: "Medicine Dose Due Notification"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.medmate_aspirin_dose_due
+        to: "on"
+    action:
+      - service: notify.mobile_app_your_phone
+        data:
+          title: "Medicine Reminder"
+          message: "Time to take your aspirin!"
+          data:
+            actions:
+              - action: "take_dose"
+                title: "Mark as Taken"
+```
+
+### Low Inventory Alert
+```yaml
+automation:
+  - alias: "Low Medicine Inventory"
+    trigger:
+      - platform: state
+        entity_id: binary_sensor.medmate_aspirin_low_inventory
+        to: "on"
+    action:
+      - service: notify.mobile_app_your_phone
+        data:
+          title: "Low Medicine Inventory"
+          message: "Aspirin inventory is running low. Consider refilling soon."
+```
+
+### Auto-fill Prescription
+```yaml
+automation:
+  - alias: "Auto Fill When Empty"
+    trigger:
+      - platform: numeric_state
+        entity_id: sensor.medmate_aspirin_inventory
+        below: 1
+    condition:
+      - condition: state
+        entity_id: binary_sensor.medmate_aspirin_prescription_active
+        state: "on"
+    action:
+      - service: button.press
+        target:
+          entity_id: button.medmate_aspirin_fill_prescription
+```
+
+## Dashboard Examples
+
+### Medicine Card
+```yaml
+type: entities
+title: Aspirin
+entities:
+  - entity: sensor.medmate_aspirin_inventory
+    name: Pills Left
+  - entity: sensor.medmate_aspirin_repeats_left
+    name: Repeats
+  - entity: sensor.medmate_aspirin_next_dose
+    name: Next Dose
+  - entity: binary_sensor.medmate_aspirin_dose_due
+    name: Dose Due
+  - entity: button.medmate_aspirin_take_morning_dose
+    name: Take Morning Dose
+  - entity: button.medmate_aspirin_fill_prescription
+    name: Fill Prescription
+```
+
+### Medicine Overview
+```yaml
+type: glance
+title: All Medicines
+entities:
+  - entity: sensor.medmate_aspirin_inventory
+    name: Aspirin
+  - entity: sensor.medmate_vitamin_d_inventory
+    name: Vitamin D
+  - entity: sensor.medmate_calcium_inventory
+    name: Calcium
+show_name: true
+show_state: true
+```
+
+## Data Storage
+
+MedMate stores all data locally in Home Assistant's storage directory:
+- Location: `config/.storage/medmate_medicines`
+- Format: JSON
+- Includes: Medicine details, schedules, prescriptions, inventory, and dose history
+
+## Troubleshooting
+
+### Medicine Not Showing Up
+1. Check that all files are in the correct directory
+2. Restart Home Assistant completely
+3. Check the logs for any error messages
+
+### Entities Not Updating
+1. Check if the coordinator is running properly
+2. Look for errors in **Settings > System > Logs**
+3. Try reloading the integration
+
+### Config Flow Issues
+1. Make sure medicine names are unique
+2. Check that all required fields are filled
+3. Verify dates are in the correct format
+
+## Advanced Usage
+
+### Custom Time Slots
+While the integration includes preset times (morning, lunchtime, dinner, night), you can extend the `DEFAULT_TIMES` dictionary in `coordinator.py` to add custom times:
+
+```python
+DEFAULT_TIMES = {
+    "morning": time(8, 0),
+    "lunchtime": time(12, 0),
+    "dinner": time(18, 0),
+    "night": time(22, 0),
+    "bedtime": time(23, 30),  # Custom time
+}
+```
+
+### Multiple Medicines
+You can add multiple medicines by running the integration setup multiple times. Each medicine gets its own device and set of entities.
+
+### Data Export
+Since data is stored in JSON format, you can easily backup or export your medicine data from the storage file.
+
+## Contributing
+
+This integration can be extended with additional features:
+- Medication interaction checking
+- Dose tracking analytics
+- Integration with health apps
+- Barcode scanning for medicine identification
+- Advanced scheduling (every other day, etc.)
+
+## Support
+
+For issues, questions, or feature requests, please check:
+1. Home Assistant logs for error messages
+2. Ensure all files are properly installed
+3. Verify your Home Assistant version compatibility
+
+---
+
+**Note**: This integration is for tracking purposes only and should not replace professional medical advice. Always consult with healthcare providers for medical decisions.