MeshCore KaiOS App

Off-grid mesh messaging for KaiOS devices via MeshCore LoRa network.

Features

• 📡 Connect to MeshCore companion radios via Bluetooth LE
• 💬 Send and receive direct messages
• 📢 Group channels for broadcast messaging
• 📇 Contact management with path learning
• 🔐 End-to-end encryption (handled by companion radio)
• 🗺️ GPS location support
• 📶 Signal strength and path visualization
• 🏠 Room server support (BBS-style messaging)

Requirements

Hardware

• KaiOS Device: Nokia 2720 Flip, Nokia 8110, Nokia 6300, or similar

  • KaiOS 2.5 or 3.0
  • Bluetooth LE support
  • Developer mode enabled (or rooted)

• Companion Radio: MeshCore-compatible LoRa device

  • Recommended: SenseCAP T1000-E
  • Also supported: Heltec WiFi LoRa 32 V3, RAK WisBlock 4631, etc.
  • Firmware: t1000e_companion_radio_ble (for T1000-E) or equivalent

Software

• Development Machine:
  • Firefox Developer Edition (or Firefox 59+ with WebIDE)
  • Python 3 (for local dev server)
  • Android Debug Bridge (adb)
  • Git

Setup

1. Enable Developer Mode on KaiOS Device

Method 1: Dial Code

Dial: *#*#33284#*#*

Method 2: Settings (if available)

Settings → Device → Developer → Enable

Enable USB Debugging:

Settings → Developer → Debugging via USB → ADB and DevTools → Enable

2. Flash Companion Radio Firmware

For SenseCAP T1000-E:

cd /Users/douwe/Desktop/Mesh/MeshCore
pio run -e t1000e_companion_radio_ble -t upload

Verify: Device should advertise as BLE device with name containing "MeshCore" or "Companion"

3. Install App on KaiOS Device

Option A: Using WebIDE (Recommended)

1. Connect KaiOS device via USB
2. Open Firefox Developer Edition
3. Go to Tools → WebIDE (or Tools → Web Developer → WebIDE)
4. Click Remote Runtime → Select your device
5. Click Open Packaged App → Select /Users/douwe/Desktop/Mesh/KaiOS/manifest.webapp
6. Click Install and Run

Option B: Using KaiOSRT (Alternative)

npm install -g kaiosrt
cd /Users/douwe/Desktop/Mesh/KaiOS
kaiosrt launch --app .

4. Grant Permissions

When prompted, allow:

• ✅ Bluetooth access
• ✅ Feature detection

Development

Local Testing

1. Start local dev server:

cd /Users/douwe/Desktop/Mesh/KaiOS
python3 -m http.server 8000

2. Open in desktop browser:

http://localhost:8000

Note: Bluetooth features won't work in desktop browser - use device for full testing.

Remote Debugging

1. Connect device via WebIDE
2. Launch app on device
3. Click Debug in WebIDE
4. Firefox DevTools will open with live console

File Structure

KaiOS/
├── manifest.webapp      # App metadata + permissions
├── index.html           # Main entry point
├── css/                 # Stylesheets
│   ├── app.css
│   ├── components.css
│   └── screens.css
├── js/                  # JavaScript modules
│   ├── app.js           # App initialization
│   ├── bluetooth.js     # BLE connection manager
│   ├── protocol.js      # Frame protocol handler
│   ├── storage.js       # IndexedDB wrapper
│   ├── session.js       # Session management
│   ├── contacts.js      # Contact CRUD
│   ├── messaging.js     # Send/receive messages
│   ├── navigation.js    # Screen routing
│   ├── ui.js            # UI controller
│   └── utils.js         # Helpers
├── screens/             # HTML templates
├── icons/               # App icons
└── docs/                # Documentation

Usage

First Time Setup

1. Launch app on KaiOS device
2. Tap Scan to search for companion radios
3. Select your companion radio from the list
4. Wait for connection (status indicator turns green)
5. Device will sync contacts automatically

Sending Messages

1. Navigate to Contacts
2. Select a contact
3. Type your message using T9 keypad
4. Press Send (center softkey)
5. Wait for delivery confirmation (✓)

Group Channels

1. Navigate to Channels
2. Join default public channel (auto-joined)
3. Send message to all channel members
4. Or create custom channel with shared key

Settings

• Set Name: Your node name visible to others
• Set Location: GPS coordinates (manual or auto)
• Radio Settings: LoRa frequency, bandwidth, spreading factor
• Reset Path: Clear learned routing path to contact

Troubleshooting

Can't connect to companion radio

Check:

• ✅ Companion radio is powered on
• ✅ Firmware is companion_radio_ble variant
• ✅ Bluetooth is enabled on KaiOS device
• ✅ Device is within ~10m range
• ✅ No other device is connected to companion radio

Solution: Reboot companion radio and restart scan.

Messages not sending

Check:

• ✅ Connection status (should be green)
• ✅ Contact exists in list
• ✅ LoRa radio is functioning
• ✅ Other mesh nodes are in range

Solution: Try resetting path to contact (Settings → Reset Path).

App crashes or freezes

Check:

• ✅ Device has enough free RAM
• ✅ No other heavy apps running
• ✅ App permissions granted

Solution: Reboot device and reinstall app.

Bluetooth disconnects frequently

Check:

• ✅ Distance between devices (<5m is ideal)
• ✅ No physical obstructions
• ✅ Companion radio battery level

Solution: Reduce polling rate in code (increase interval).

Protocol Reference

BLE Service

• Service UUID: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E (Nordic UART)
• RX Characteristic: 6E400002-B5A3-F393-E0A9-E50E24DCCA9E (Write)
• TX Characteristic: 6E400003-B5A3-F393-E0A9-E50E24DCCA9E (Read)

Frame Protocol

See docs/PROTOCOL.md for detailed frame format documentation.

Key Commands

• CMD_APP_START (1) - Initialize session
• CMD_SEND_TXT_MSG (2) - Send direct message
• CMD_SEND_CHANNEL_TXT_MSG (3) - Send channel message
• CMD_GET_CONTACTS (4) - Sync contact list
• CMD_SYNC_NEXT_MESSAGE (10) - Pull queued messages

Architecture

┌─────────────┐        BLE (NUS)          ┌──────────────┐
│  KaiOS App  │ ◄────────────────────────► │  Companion   │
│             │    Binary Frames          │    Radio     │
│             │    (max 172 bytes)        │  (T1000-E)   │
└─────────────┘                            └──────┬───────┘
                                                  │ LoRa
                                           ┌──────▼───────┐
                                           │ Mesh Network │
                                           │ (Multi-hop)  │
                                           └──────────────┘

Polling Strategy

KaiOS doesn't support BLE notifications, so we poll the TX characteristic:

• Active: 500ms (during messaging)
• Normal: 1000ms (idle but connected)
• Idle: 2000ms (no activity for 30s)
• Background: 5000ms (app backgrounded)

Performance

Battery Life

• Bluetooth connection: ~8-12 hours continuous
• Active messaging: ~6-8 hours
• Idle (screen off): ~16-24 hours

Memory Usage

• Initial load: ~15MB
• With 100 contacts: ~20MB
• With 500 messages: ~25MB

Limitations

• Max contacts: 350 (companion radio limit)
• Max message length: ~150 characters (frame size limit)
• Max polling rate: 500ms (KaiOS BLE performance)

Contributing

See docs/DEVELOPMENT.md for development guidelines.

License

This project is independent and not officially affiliated with MeshCore.

MeshCore library: See /Users/douwe/Desktop/Mesh/MeshCore/license.txt

Resources

• MeshCore Docs: /Users/douwe/Desktop/Mesh/MeshCore/README.md
• Research Document: /Users/douwe/Desktop/Mesh/MESHCORE_KAIOS_RESEARCH.md
• Development Tools: /Users/douwe/Desktop/Mesh/DEVELOPMENT_TOOLS.md
• KaiOS Developer Portal: https://developer.kaiostech.com
• KaiOS Community: https://kaios.dev

Support

For issues with:

• MeshCore firmware: See MeshCore repository
• KaiOS app: Check /Users/douwe/Desktop/Mesh/KaiOS/docs/
• T1000-E hardware: https://wiki.seeedstudio.com/sensecap_t1000_e/

Changelog

v0.1.0 (Current)

• Initial development version
• Basic BLE connection
• Contact sync
• Direct messaging
• Group channels
• Settings screen

Roadmap

• Message history persistence
• Multi-device support
• Voice messages (audio encoding)
• Map view with node locations
• Room server improvements
• Offline queue management
• Performance optimizations