mirror of
https://github.com/zjs81/meshcore-open.git
synced 2026-06-14 22:55:12 +10:00
zjs81
ea657a964a
- Replaced sqflite with shared_preferences for local key-value storage in README.md - Updated gradle.properties to include builtInKotlin and newDsl flags - Enhanced translation feature documentation in additional-features.md - Modified BLE protocol documentation to include new command and response codes in ble-protocol.md - Clarified channel management details in channels.md - Improved chat and messaging documentation, including message path viewing and translation options in chat-and-messaging.md - Updated contacts management details in contacts.md - Revised map and location documentation for inferred locations and user interface changes in map-and-location.md - Adjusted navigation flow in navigation.md to reflect changes in screen transitions - Updated notification system details in notifications.md - Enhanced repeater management documentation in repeater-management.md - Clarified scanner and connection process in scanner-and-connection.md - Reorganized settings documentation for better clarity and added new node and location settings in settings.md
119 lines
5.6 KiB
Markdown
119 lines
5.6 KiB
Markdown
# Contacts
|
||
|
||
## Overview
|
||
|
||
The Contacts screen is the primary hub for managing mesh nodes your radio has a relationship with. A "contact" is any node whose cryptographic advertisement has been received — it can be a chat user, repeater, room server, or sensor.
|
||
|
||
## How to Access
|
||
|
||
- QuickSwitchBar tab 0 (leftmost) from Channels or Map screens (Channels is shown first after connecting)
|
||
- Back navigation from Chat or Settings screens
|
||
|
||
## Contact Types
|
||
|
||
| Type | Avatar Color | Icon | Description |
|
||
|---|---|---|---|
|
||
| Chat | Blue | Initials / emoji | Another user's mesh radio |
|
||
| Repeater | Amber | Cell tower | A mesh repeater/relay node |
|
||
| Room | Magenta | Meeting room | A room server for group chat |
|
||
| Sensor | Teal | Sensors | A sensor device |
|
||
|
||
## Contact List
|
||
|
||
Each contact is displayed as a list tile showing:
|
||
|
||
- **Avatar**: Color-coded circle with type icon (or first emoji of the contact's name if it starts with one)
|
||
- **Name**: Contact name (single line)
|
||
- **Path label**: "Direct", "N hops", or "Flood" (with forced variants if a path override is active)
|
||
- **Public key**: Shortened hex format `<XXXXXXXX...XXXXXXXX>`
|
||
- **Unread badge**: Red pill with count (if unread messages exist)
|
||
- **Last seen**: Relative timestamp ("Now", "5 mins ago", "2 hours ago", "3 days ago"). For chat contacts, this shows whichever is more recent: the last advertisement time or the last message time
|
||
- **Favorite star**: Amber star icon if favorited
|
||
- **Location pin**: Grey pin icon if the contact has GPS coordinates
|
||
|
||
Pull-to-refresh re-fetches the full contact list from the device.
|
||
|
||
## Search and Filter
|
||
|
||
A toolbar at the top provides:
|
||
|
||
**Search**: Matches contact name (case-insensitive) or public key hex prefix. Debounced at 300ms.
|
||
|
||
**Sort options**:
|
||
- Latest Messages (by most recent message)
|
||
- Heard Recently (by last seen / last message)
|
||
- A–Z (alphabetical)
|
||
|
||
**Filter options**:
|
||
- All, Favorites, Users, Repeaters, Room Servers, Unread Only
|
||
|
||
## Contact Groups
|
||
|
||
Groups are a client-side organizational feature for grouping contacts.
|
||
|
||
- **Create a group**: Tap the group dropdown → "+" icon → enter name → select members → Save
|
||
- **Edit a group**: Group dropdown → pencil icon next to the group
|
||
- **Delete a group**: Group dropdown → trash icon next to the group
|
||
- **Filter by group**: Select a group from the dropdown to show only its members
|
||
|
||
Groups are stored per radio identity (scoped by public key).
|
||
|
||
**Validation rules**: Group names cannot be empty, cannot be "all" (reserved, case-insensitive), and must be unique (case-insensitive). The group creation dialog includes a built-in search field to filter contacts when selecting members. Creating a new group automatically selects it as the active filter.
|
||
|
||
## Tap Actions
|
||
|
||
| Contact Type | Action on Tap |
|
||
|---|---|
|
||
| Chat / Sensor | Opens ChatScreen for direct messaging |
|
||
| Repeater | Shows password login dialog → opens RepeaterHubScreen |
|
||
| Room | Shows password login dialog → opens ChatScreen for room chat |
|
||
|
||
## Long-Press / Right-Click Menu
|
||
|
||
| Action | Availability | Description |
|
||
|---|---|---|
|
||
| Ping | Repeaters only | Opens PathTraceMapScreen targeting the repeater |
|
||
| Path Trace | Rooms (always); Chat/Sensor only if `pathLength > 0` | Opens PathTraceMapScreen. For rooms, label shows "Ping" when no path bytes are known, "Path Trace" when path bytes are available |
|
||
| Manage Repeater | Repeaters only | Login dialog → RepeaterHubScreen |
|
||
| Room Login | Rooms only | Login dialog → ChatScreen |
|
||
| Room Management | Rooms only | Login dialog → RepeaterHubScreen (management mode) |
|
||
| Add/Remove Favorite | All types | Toggles the favorite flag |
|
||
| Share Contact | All types | Requests advert from device → copies `meshcore://<hex>` URI to clipboard |
|
||
| Share Contact Zero-Hop | All types | Broadcasts the contact's advertisement one hop |
|
||
| Delete Contact | All types | Confirmation dialog → removes from device and clears messages |
|
||
|
||
## App Bar Menus
|
||
|
||
The Contacts screen has a single **three-dot overflow menu** (`⋮`) in the app bar:
|
||
|
||
- Discovered Contacts — opens the DiscoveryScreen
|
||
- Add Contact from Clipboard — reads a `meshcore://<hex>` URI from clipboard and imports it
|
||
- *(divider)*
|
||
- Zero-Hop Advert — broadcasts your advertisement to immediately adjacent nodes
|
||
- Flood Advert — broadcasts across the full mesh network
|
||
- Copy Advert to Clipboard — copies your `meshcore://<hex>` URI for sharing externally
|
||
- *(divider)*
|
||
- Disconnect — disconnects from the device
|
||
- Settings — opens the Settings screen
|
||
|
||
A **floating action button** (person-add icon) provides a shortcut sheet to "Add Contact from Clipboard" or "Discovered Contacts".
|
||
|
||
## Adding Contacts
|
||
|
||
### Automatic (Passive)
|
||
When the radio hears an advertisement, the contact appears automatically if auto-add is enabled for that type (configurable in Settings → Contact Settings).
|
||
|
||
### Import from Clipboard
|
||
Overflow menu (or the FAB shortcut) → "Add Contact from Clipboard". Reads a `meshcore://<hex>` URI from clipboard and imports it to the device.
|
||
|
||
### Import from Discovered Contacts
|
||
Overflow menu → "Discovered Contacts". Shows nodes heard passively that haven't been added yet. Tap to immediately import (no confirmation dialog), or long-press for more options (Copy URI, Delete). The Discovery screen has its own search bar, type filters (Users, Repeaters, Rooms), and sort options (Last Seen, A-Z). An overflow "Delete All" option clears all discovered contacts.
|
||
|
||
## Contact Sharing Format
|
||
|
||
Contacts are shared using the `meshcore://` URI scheme:
|
||
```
|
||
meshcore://<hex-encoded-advertisement-packet>
|
||
```
|
||
This contains the node's public key and metadata. Paste it into another MeshCore app to import.
|