Initial commit
This commit is contained in:
170
README_APP.md
Normal file
170
README_APP.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# BM Manager
|
||||
|
||||
A Flutter application for managing DMR devices and talkgroups through the BrandMeister network API, based on the PyroMeister Manager iOS app.
|
||||
|
||||
## Features
|
||||
|
||||
- **Secure Authentication**: Token-based authentication with secure keychain storage
|
||||
- **Device Management**: View and manage all your BrandMeister devices
|
||||
- **Talkgroup Management**: Link and unlink static talkgroups to/from devices
|
||||
- **Material Design**: Clean, modern UI with light/dark theme support
|
||||
- **Pull-to-Refresh**: Easy data refresh on all screens
|
||||
- **Error Handling**: Comprehensive error handling with user-friendly messages
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
lib/
|
||||
├── main.dart # App entry point with Provider setup
|
||||
├── models/ # Data models
|
||||
│ ├── device.dart # Device model
|
||||
│ ├── user_info.dart # User information model
|
||||
│ ├── static_talkgroup.dart # Talkgroup model
|
||||
│ ├── device_profile.dart # Device profile model
|
||||
│ └── cluster.dart # Cluster model
|
||||
├── services/ # Business logic and API
|
||||
│ ├── brandmeister_client.dart # API client for BrandMeister
|
||||
│ └── authentication_manager.dart # Auth and state management
|
||||
└── views/ # UI screens
|
||||
├── content_view.dart # Root routing view
|
||||
├── welcome_view.dart # Authentication screen
|
||||
├── main_view.dart # Device list screen
|
||||
├── device_detail_view.dart # Device details & talkgroups
|
||||
└── link_talkgroup_view.dart # Add talkgroup modal
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
The app integrates with the BrandMeister API v2:
|
||||
|
||||
**Base URL**: `https://api.brandmeister.network/v2`
|
||||
|
||||
### Key Endpoints Used
|
||||
|
||||
- `POST /user/whoAmI` - Verify authentication and get user info
|
||||
- `GET /device/byCall?callsign={callsign}` - Get devices by callsign
|
||||
- `GET /device/{id}` - Get device details
|
||||
- `GET /device/{id}/talkgroup` - Get device talkgroups
|
||||
- `POST /device/{id}/talkgroup` - Link talkgroup to device
|
||||
- `DELETE /device/{id}/talkgroup/{slot}/{talkgroup}` - Unlink talkgroup
|
||||
- `GET /talkgroup` - Get all available talkgroups
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **flutter**: SDK
|
||||
- **http**: HTTP client for API calls
|
||||
- **flutter_secure_storage**: Secure keychain/keystore storage for API token
|
||||
- **provider**: State management solution
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Flutter SDK (3.10.7+)
|
||||
- BrandMeister API token (get from https://brandmeister.network)
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone the repository
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
fvm flutter pub get
|
||||
```
|
||||
|
||||
3. Run the app:
|
||||
```bash
|
||||
fvm flutter run
|
||||
```
|
||||
|
||||
### First Launch
|
||||
|
||||
1. The app will show the Welcome screen
|
||||
2. Enter your BrandMeister API token
|
||||
3. Tap "Sign In" to authenticate
|
||||
4. Your token is securely stored for future sessions
|
||||
|
||||
## Usage
|
||||
|
||||
### Viewing Devices
|
||||
|
||||
- After authentication, you'll see a list of all your BrandMeister devices
|
||||
- Pull down to refresh the device list
|
||||
- Tap any device to view details
|
||||
|
||||
### Managing Talkgroups
|
||||
|
||||
- In the device detail screen, view all linked static talkgroups
|
||||
- Tap the "+" button to link a new talkgroup
|
||||
- Enter the talkgroup ID and select timeslot (TS1 or TS2)
|
||||
- Tap the delete icon to unlink a talkgroup
|
||||
|
||||
### Logout
|
||||
|
||||
- Tap the logout icon in the app bar on the main screen
|
||||
- Your token will be securely removed
|
||||
|
||||
## Architecture
|
||||
|
||||
### State Management
|
||||
|
||||
The app uses **Provider** for state management with a `ChangeNotifier`:
|
||||
|
||||
- `AuthenticationManager` - Central service managing:
|
||||
- Authentication state
|
||||
- Secure token storage
|
||||
- API operations
|
||||
- User information
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. View requests data from `AuthenticationManager`
|
||||
2. `AuthenticationManager` calls `BrandmeisterClient`
|
||||
3. `BrandmeisterClient` makes HTTP requests to BrandMeister API
|
||||
4. Responses are parsed into model objects
|
||||
5. Views update UI with new data
|
||||
|
||||
### Security
|
||||
|
||||
- API tokens stored in platform-specific secure storage:
|
||||
- iOS: Keychain
|
||||
- Android: Encrypted SharedPreferences
|
||||
- macOS: Keychain
|
||||
- Windows: Windows Credential Store
|
||||
- Linux: Secret Service API
|
||||
|
||||
## Error Handling
|
||||
|
||||
The app includes comprehensive error handling:
|
||||
|
||||
- Network errors with retry options
|
||||
- API errors with clear messages
|
||||
- Form validation
|
||||
- Loading states with progress indicators
|
||||
- Success/failure feedback with SnackBars
|
||||
|
||||
## Platform Support
|
||||
|
||||
- ✅ iOS
|
||||
- ✅ Android
|
||||
- ✅ macOS
|
||||
- ✅ Windows
|
||||
- ✅ Linux
|
||||
- ✅ Web
|
||||
|
||||
## Differences from iOS Version
|
||||
|
||||
While maintaining feature parity with PyroMeister Manager, this Flutter version:
|
||||
|
||||
- Uses Provider instead of SwiftUI's Observable
|
||||
- Uses flutter_secure_storage instead of native Keychain
|
||||
- Implements Material Design instead of iOS native design
|
||||
- Supports multiple platforms (not just iOS)
|
||||
- Uses Modal Bottom Sheet for "Link Talkgroup" instead of a separate view
|
||||
|
||||
## License
|
||||
|
||||
This is a personal project for managing BrandMeister devices. Please ensure you have appropriate authorization to access the BrandMeister API.
|
||||
|
||||
## Credits
|
||||
|
||||
Based on **PyroMeister Manager** iOS app structure and functionality.
|
||||
Reference in New Issue
Block a user