303 lines
8.6 KiB
Markdown
303 lines
8.6 KiB
Markdown
# 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. |