Best Practices

MAVS Setup & Usage Guide

🚀 Quick Start

Get your MAVS device up and running in minutes:

  1. Charge your MAVS device fully before first use
  2. Download the MAVS companion app (iOS/Android/Desktop)
  3. Pair via Bluetooth using the pairing button
  4. Configure your first AI agent
  5. Say the wake word and start talking!

🔧 Hardware Setup

Optimal Placement

  • Place MAVS on a stable, flat surface
  • Position 2-6 feet from your typical speaking position
  • Avoid placing near loud speakers or HVAC vents
  • Keep away from direct sunlight and heat sources

Connectivity

  • Bluetooth: Best for mobile use and portability
  • WiFi: Recommended for stationary use and lower latency
  • USB-C: Direct connection for developers and lowest latency

Battery Care

  • Use the included charger or Qi wireless charging
  • Avoid complete discharge—charge when below 20%
  • Firmware optimizes battery during overnight charging

🤖 Agent Configuration

Setting Up Agents

  • Use the app to add AI agents (OpenAI, Claude, Gemini, etc.)
  • Enter your API keys—they're encrypted on-device
  • Assign each agent to a ring position (1-4)
  • Customize wake words for each agent (optional)

Recommended Agent Setups

  • Development: Coding assistant + Documentation + Git helper
  • Productivity: Calendar + Email + Task manager + Notes
  • Smart Home: Lights + Climate + Security + Media
  • Creative: Writing assistant + Research + Brainstorming

🎙️ Voice Interaction Tips

Speaking Naturally

  • Speak at normal volume—MAVS has sensitive microphones
  • Don't shout or whisper; natural speech works best
  • Brief pauses help with command recognition
  • Feel free to speak in full sentences

Switching Agents

  • Touch Ring: Rotate to select, tap to confirm
  • Voice Switch: Say "Switch to [agent name]"
  • Quick Switch: Double-tap to return to last agent

Commands & Feedback

  • LED color indicates active agent
  • Haptic feedback confirms agent switches
  • Say "Cancel" to abort a command
  • Hold the mute button for instant privacy

💻 Developer Guide

SDK Installation

Install the MAVS SDK for your preferred language:

  • Python: pip install mavs-sdk
  • JavaScript: npm install @crateso/mavs
  • Swift: Add via Swift Package Manager
  • Kotlin: Add via Gradle

API Best Practices

  • Use WebSocket connections for real-time events
  • Implement proper error handling and reconnection logic
  • Cache agent configurations locally for faster startup
  • Use the event system for responsive UI updates

Custom Agents

  • Implement the MAVSAgent interface
  • Handle voice input as audio stream or transcribed text
  • Return responses as text or audio stream
  • Register your agent with the MAVS runtime

🔒 Security Best Practices

Account Security

  • Use a strong, unique password for your MAVS account
  • Enable two-factor authentication
  • Review connected devices periodically
  • Revoke access for devices you no longer use

API Key Management

  • Never share your API keys or screenshots showing them
  • Use environment variables in development
  • Rotate keys periodically, especially if compromised
  • Set spending limits on AI provider accounts

Privacy Settings

  • Review voice history settings—off by default
  • Use the mute button in sensitive environments
  • Disable agents you're not actively using
  • Audit connected third-party services regularly

🛠️ Troubleshooting

Connection Issues

  • Ensure Bluetooth/WiFi is enabled on your device
  • Move closer to your router for WiFi
  • Restart MAVS by holding power for 10 seconds
  • Re-pair the device in the app if needed

Voice Recognition Problems

  • Check for obstructions over the microphones
  • Reduce background noise if possible
  • Retrain the wake word in quiet environment
  • Update to the latest firmware

Agent Response Issues

  • Verify your API keys are valid and have credits
  • Check internet connectivity
  • Try switching to a different agent to isolate the issue
  • Review agent logs in the app for errors

🔄 Firmware Updates

  • Keep firmware updated for best performance and security
  • Updates are downloaded over WiFi automatically
  • Installation requires user confirmation (unless critical security)
  • Don't disconnect power during updates
  • Check release notes in the app for new features

🆘 Getting Help

Support Resources

  • Documentation: docs.crateso.com/mavs
  • Developer Discord: discord.gg/crateso
  • GitHub Issues: github.com/crateso/mavs-sdk
  • Email Support: support@crateso.com

Before Contacting Support

  • Note your firmware version (Settings → About)
  • Describe steps to reproduce the issue
  • Include error messages if any
  • Try basic troubleshooting first

✨ Pro Tips

  • Create agent shortcuts for common multi-step tasks
  • Use the companion app widgets for quick access
  • Join the developer community for integration ideas
  • Experiment with the SDK to create custom experiences
  • Provide feedback—we're constantly improving MAVS!

Happy building with MAVS! 🎙️