diff --git a/README.md b/README.md index d4becf0..0a1f161 100644 --- a/README.md +++ b/README.md @@ -1,213 +1,103 @@ -# Strike Bitcoin Sensor for Home Assistant +# Home Assistant Custom Integrations -A custom Home Assistant integration that fetches Bitcoin price data from the Strike API and creates sensor entities for monitoring cryptocurrency prices. +A collection of custom Home Assistant integrations for various services and devices. [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs) -## Features +## Available Integrations -- 🔄 Real-time Bitcoin (BTC) price tracking from Strike API -- 💱 Configurable currency pairs (default: BTC/USD) -- ⏱️ Customizable update intervals -- 🔐 Secure API key storage -- 🎨 Home Assistant UI configuration flow -- 📊 Additional state attributes (currency, source, last update) -- 🛡️ Comprehensive error handling and logging -- ✨ Follows Home Assistant development best practices +### 🪙 Strike Bitcoin Sensor + +Real-time Bitcoin price tracking using the Strike API. + +**Features:** +- Real-time BTC price monitoring +- Configurable currency pairs +- Customizable update intervals +- Secure API key storage +- Home Assistant UI configuration + +**[Documentation](integrations/strike/)** | **[Installation Guide](integrations/strike/README.md#installation)** ## Installation ### HACS (Recommended) +Each integration in this repository is available through HACS as a custom repository. + 1. Open HACS in your Home Assistant instance 2. Click on "Integrations" 3. Click the three dots in the top right corner 4. Select "Custom repositories" -5. Add the repository URL: `https://github.com/yourusername/hass-to-be-good` +5. Add the repository URL for the specific integration: + - Strike: `https://git.martien.io/Martien/hass-to-be-good` (then navigate to integrations/strike) 6. Select category: "Integration" 7. Click "Add" -8. Search for "Strike Bitcoin" in HACS +8. Search for the integration name in HACS 9. Click "Download" 10. Restart Home Assistant ### Manual Installation -1. Copy the `custom_components/strike` folder to your Home Assistant `custom_components` directory -2. Restart Home Assistant +1. Navigate to the specific integration folder (e.g., `integrations/strike/`) +2. Copy the `custom_components/` folder to your Home Assistant `custom_components` directory +3. Restart Home Assistant +4. Follow the integration-specific setup instructions -## Configuration - -### Prerequisites - -You need a Strike API key to use this integration: - -1. Visit [Strike](https://strike.me/) and create an account -2. Navigate to the API section in your Strike dashboard -3. Generate a new API key -4. Copy the API key for use in Home Assistant - -### Setup via UI - -1. Go to **Settings** → **Devices & Services** -2. Click **+ Add Integration** -3. Search for **Strike Bitcoin** -4. Enter your Strike API key -5. (Optional) Configure currency pair (default: BTCUSD) -6. (Optional) Set update interval in seconds (default: 300 seconds / 5 minutes) -7. Click **Submit** - -## Usage - -Once configured, the integration will create a sensor entity: - -- **Entity ID**: `sensor.strike_btcusd` -- **State**: Current Bitcoin price -- **Unit**: Currency (e.g., USD) -- **Icon**: `mdi:bitcoin` - -### State Attributes - -The sensor provides additional information as attributes: - -- `currency`: Target currency (e.g., USD) -- `source`: Currency pair (e.g., BTC/USD) -- `last_update`: Timestamp of last update - -### Example Automation - -```yaml -automation: - - alias: "Bitcoin Price Alert" - trigger: - - platform: numeric_state - entity_id: sensor.strike_btcusd - above: 50000 - action: - - service: notify.notify - data: - message: "Bitcoin price is above $50,000!" -``` - -### Example Lovelace Card - -```yaml -type: entities -entities: - - entity: sensor.strike_btcusd - name: Bitcoin Price - icon: mdi:bitcoin -``` - -## Configuration Options - -### Options Flow - -You can modify the integration settings after setup: - -1. Go to **Settings** → **Devices & Services** -2. Find **Strike Bitcoin** integration -3. Click **Configure** -4. Adjust the update interval -5. Click **Submit** - -## Troubleshooting - -### Integration Not Loading - -- Check Home Assistant logs for errors -- Verify API key is correct -- Ensure you have internet connectivity -- Restart Home Assistant - -### API Errors - -Common errors and solutions: - -- **401 Unauthorized**: Invalid API key - regenerate in Strike dashboard -- **403 Forbidden**: API key doesn't have required permissions -- **Connection timeout**: Check network connectivity or increase timeout in `const.py` - -### Enable Debug Logging - -Add to your `configuration.yaml`: - -```yaml -logger: - default: info - logs: - custom_components.strike: debug -``` - -## Development - -### Repository Structure +## Repository Structure ``` hass-to-be-good/ -├── custom_components/ -│ └── strike/ -│ ├── __init__.py # Integration setup -│ ├── config_flow.py # Configuration UI -│ ├── const.py # Constants and configuration -│ ├── manifest.json # Integration metadata -│ └── sensor.py # Sensor implementation +├── README.md # This file ├── .gitignore -├── hacs.json # HACS configuration -└── README.md +└── integrations/ + └── strike/ # Strike Bitcoin integration + ├── README.md # Integration documentation + ├── hacs.json # HACS configuration + └── custom_components/ + └── strike/ # Integration code + ├── __init__.py + ├── config_flow.py + ├── const.py + ├── manifest.json + └── sensor.py ``` -### Contributing +## Contributing -Contributions are welcome! Please: +Contributions are welcome! To add a new integration or improve existing ones: 1. Fork the repository 2. Create a feature branch -3. Make your changes -4. Submit a pull request +3. Add your integration in the `integrations/` directory following the existing structure +4. Include proper documentation (README.md, hacs.json, etc.) +5. Submit a pull request -### Testing +### Integration Guidelines -Before submitting changes: - -1. Test the integration in a Home Assistant development environment -2. Verify configuration flow works correctly -3. Check logs for errors or warnings -4. Ensure code follows Home Assistant style guidelines - -## Strike API Reference - -This integration uses the Strike API v1: - -- **Base URL**: `https://api.strike.me` -- **Endpoint**: `/v1/rates/ticker` -- **Authentication**: Bearer token (API key) -- **Documentation**: [Strike API Docs](https://docs.strike.me/) - -## License - -This project is provided as-is for educational and personal use. +Each integration should: +- Be in its own folder under `integrations/` +- Include a `README.md` with installation and usage instructions +- Include a `hacs.json` configuration file +- Follow Home Assistant development best practices +- Include proper error handling and logging +- Use async/await patterns +- Include type hints and docstrings ## Support For issues, questions, or feature requests: -- Open an issue on [GitHub](https://github.com/yourusername/hass-to-be-good/issues) +- Open an issue on [Gitea](https://git.martien.io/Martien/hass-to-be-good/issues) - Check existing issues for solutions +- Include integration name in issue title - Provide Home Assistant logs when reporting bugs -## Changelog +## License -### Version 1.0.0 - -- Initial release -- Bitcoin price sensor with Strike API integration -- UI configuration flow -- Configurable update intervals -- Secure API key storage -- Comprehensive error handling +This project is provided as-is for educational and personal use. ## Acknowledgments - Built for [Home Assistant](https://www.home-assistant.io/) -- Uses [Strike API](https://strike.me/) - Follows [Home Assistant integration development guidelines](https://developers.home-assistant.io/) diff --git a/integrations/strike/README.md b/integrations/strike/README.md new file mode 100644 index 0000000..15f988d --- /dev/null +++ b/integrations/strike/README.md @@ -0,0 +1,213 @@ +# Strike Bitcoin Sensor for Home Assistant + +A custom Home Assistant integration that fetches Bitcoin price data from the Strike API and creates sensor entities for monitoring cryptocurrency prices. + +[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/custom-components/hacs) + +## Features + +- 🔄 Real-time Bitcoin (BTC) price tracking from Strike API +- 💱 Configurable currency pairs (default: BTC/USD) +- ⏱️ Customizable update intervals +- 🔐 Secure API key storage +- 🎨 Home Assistant UI configuration flow +- 📊 Additional state attributes (currency, source, last update) +- 🛡️ Comprehensive error handling and logging +- ✨ Follows Home Assistant development best practices + +## Installation + +### HACS (Recommended) + +1. Open HACS in your Home Assistant instance +2. Click on "Integrations" +3. Click the three dots in the top right corner +4. Select "Custom repositories" +5. Add the repository URL: `https://git.martien.io/Martien/hass-to-be-good` +6. Select category: "Integration" +7. Click "Add" +8. Search for "Strike Bitcoin" in HACS +9. Click "Download" +10. Restart Home Assistant + +### Manual Installation + +1. Copy the `custom_components/strike` folder to your Home Assistant `custom_components` directory +2. Restart Home Assistant + +## Configuration + +### Prerequisites + +You need a Strike API key to use this integration: + +1. Visit [Strike](https://strike.me/) and create an account +2. Navigate to the API section in your Strike dashboard +3. Generate a new API key +4. Copy the API key for use in Home Assistant + +### Setup via UI + +1. Go to **Settings** → **Devices & Services** +2. Click **+ Add Integration** +3. Search for **Strike Bitcoin** +4. Enter your Strike API key +5. (Optional) Configure currency pair (default: BTCUSD) +6. (Optional) Set update interval in seconds (default: 300 seconds / 5 minutes) +7. Click **Submit** + +## Usage + +Once configured, the integration will create a sensor entity: + +- **Entity ID**: `sensor.strike_btcusd` +- **State**: Current Bitcoin price +- **Unit**: Currency (e.g., USD) +- **Icon**: `mdi:bitcoin` + +### State Attributes + +The sensor provides additional information as attributes: + +- `currency`: Target currency (e.g., USD) +- `source`: Currency pair (e.g., BTC/USD) +- `last_update`: Timestamp of last update + +### Example Automation + +```yaml +automation: + - alias: "Bitcoin Price Alert" + trigger: + - platform: numeric_state + entity_id: sensor.strike_btcusd + above: 50000 + action: + - service: notify.notify + data: + message: "Bitcoin price is above $50,000!" +``` + +### Example Lovelace Card + +```yaml +type: entities +entities: + - entity: sensor.strike_btcusd + name: Bitcoin Price + icon: mdi:bitcoin +``` + +## Configuration Options + +### Options Flow + +You can modify the integration settings after setup: + +1. Go to **Settings** → **Devices & Services** +2. Find **Strike Bitcoin** integration +3. Click **Configure** +4. Adjust the update interval +5. Click **Submit** + +## Troubleshooting + +### Integration Not Loading + +- Check Home Assistant logs for errors +- Verify API key is correct +- Ensure you have internet connectivity +- Restart Home Assistant + +### API Errors + +Common errors and solutions: + +- **401 Unauthorized**: Invalid API key - regenerate in Strike dashboard +- **403 Forbidden**: API key doesn't have required permissions +- **Connection timeout**: Check network connectivity or increase timeout in `const.py` + +### Enable Debug Logging + +Add to your `configuration.yaml`: + +```yaml +logger: + default: info + logs: + custom_components.strike: debug +``` + +## Development + +### Repository Structure + +``` +hass-to-be-good/ +├── custom_components/ +│ └── strike/ +│ ├── __init__.py # Integration setup +│ ├── config_flow.py # Configuration UI +│ ├── const.py # Constants and configuration +│ ├── manifest.json # Integration metadata +│ └── sensor.py # Sensor implementation +├── .gitignore +├── hacs.json # HACS configuration +└── README.md +``` + +### Contributing + +Contributions are welcome! Please: + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Submit a pull request + +### Testing + +Before submitting changes: + +1. Test the integration in a Home Assistant development environment +2. Verify configuration flow works correctly +3. Check logs for errors or warnings +4. Ensure code follows Home Assistant style guidelines + +## Strike API Reference + +This integration uses the Strike API v1: + +- **Base URL**: `https://api.strike.me` +- **Endpoint**: `/v1/rates/ticker` +- **Authentication**: Bearer token (API key) +- **Documentation**: [Strike API Docs](https://docs.strike.me/) + +## License + +This project is provided as-is for educational and personal use. + +## Support + +For issues, questions, or feature requests: + +- Open an issue on [Gitea](https://git.martien.io/Martien/hass-to-be-good/issues) +- Check existing issues for solutions +- Provide Home Assistant logs when reporting bugs + +## Changelog + +### Version 1.0.0 + +- Initial release +- Bitcoin price sensor with Strike API integration +- UI configuration flow +- Configurable update intervals +- Secure API key storage +- Comprehensive error handling + +## Acknowledgments + +- Built for [Home Assistant](https://www.home-assistant.io/) +- Uses [Strike API](https://strike.me/) +- Follows [Home Assistant integration development guidelines](https://developers.home-assistant.io/) diff --git a/custom_components/strike/__init__.py b/integrations/strike/custom_components/strike/__init__.py similarity index 100% rename from custom_components/strike/__init__.py rename to integrations/strike/custom_components/strike/__init__.py diff --git a/custom_components/strike/config_flow.py b/integrations/strike/custom_components/strike/config_flow.py similarity index 100% rename from custom_components/strike/config_flow.py rename to integrations/strike/custom_components/strike/config_flow.py diff --git a/custom_components/strike/const.py b/integrations/strike/custom_components/strike/const.py similarity index 100% rename from custom_components/strike/const.py rename to integrations/strike/custom_components/strike/const.py diff --git a/custom_components/strike/manifest.json b/integrations/strike/custom_components/strike/manifest.json similarity index 57% rename from custom_components/strike/manifest.json rename to integrations/strike/custom_components/strike/manifest.json index 037bd9f..c3f2f23 100644 --- a/custom_components/strike/manifest.json +++ b/integrations/strike/custom_components/strike/manifest.json @@ -3,8 +3,8 @@ "name": "Strike Bitcoin", "codeowners": ["@martien"], "config_flow": true, - "documentation": "https://github.com/martien/hass-to-be-good", - "issue_tracker": "https://github.com/martien/hass-to-be-good/issues", + "documentation": "https://git.martien.io/Martien/hass-to-be-good", + "issue_tracker": "https://git.martien.io/Martien/hass-to-be-good/issues", "requirements": ["aiohttp>=3.8.0"], "version": "1.0.0", "iot_class": "cloud_polling" diff --git a/custom_components/strike/sensor.py b/integrations/strike/custom_components/strike/sensor.py similarity index 100% rename from custom_components/strike/sensor.py rename to integrations/strike/custom_components/strike/sensor.py diff --git a/hacs.json b/integrations/strike/hacs.json similarity index 100% rename from hacs.json rename to integrations/strike/hacs.json