Skip to content

MACOS_QUICKSTART.md

Latest commit

 

History

History
207 lines (158 loc) · 4.5 KB

MACOS_QUICKSTART.md

File metadata and controls

207 lines (158 loc) · 4.5 KB
Raw

macOS Quick Start Guide

USB Drive Detection & Flashing on macOS

Prerequisites

  • macOS 10.10 or later
  • Python 3.7+ installed
  • A USB drive (for testing/flashing)

Quick Test

  1. Test if USB detection works:

    python3 test_macos_usb.py

  2. Manually test diskutil:

    diskutil list

    You should see a list of all disks including any USB drives.

Using the Cold Wallet System

Option 1: Basic Usage (No Root Required)

# Run the main application
python3 main.py

# The system will automatically:
# - Detect your USB drive
# - Mount it if needed
# - Set up the wallet structure

Option 2: Flash a USB Drive (Root Required)

# Build and flash
sudo python3 flash_usb.py --build

# Or just flash an existing image
sudo python3 flash_usb.py

Common macOS Disk Paths

  • Main disk: /dev/disk0 (your Mac's internal drive - DO NOT FLASH THIS!)
  • USB drives: /dev/disk2, /dev/disk3, etc.
  • Raw devices (faster): /dev/rdisk2, /dev/rdisk3, etc.
  • Mount points: /Volumes/VOLUME_NAME

Finding Your USB Drive

# Before plugging in USB, run:
diskutil list

# Plug in your USB drive, then run again:
diskutil list

# The new disk that appears is your USB drive
# It will be labeled as (external, physical)

Manual Operations

Unmount a USB Drive

diskutil unmount /Volumes/YOUR_USB_NAME
# or force unmount:
diskutil unmount force /Volumes/YOUR_USB_NAME

Mount a USB Drive

diskutil mount /dev/disk2s1

Eject a USB Drive Safely

diskutil eject /dev/disk2

Format a USB Drive (⚠️ ERASES DATA!)

# Format as FAT32 (Windows compatible)
diskutil eraseDisk FAT32 COLDSTAR MBR /dev/disk2

# Format as ExFAT (better for large files)
diskutil eraseDisk ExFAT COLDSTAR GPT /dev/disk2

Troubleshooting

"Resource busy" Error

# Find what's using the disk:
lsof | grep /dev/disk2

# Force unmount:
diskutil unmount force /Volumes/YOUR_USB

Disk Not Appearing

# Refresh disk list:
diskutil list

# Check system log:
log show --predicate 'eventMessage contains "disk"' --last 5m

Permission Denied

# For flashing operations, use sudo:
sudo python3 flash_usb.py

# For basic detection, no sudo needed:
python3 main.py

Performance Tips

  1. Use raw disk device for faster writes:

    • Instead of /dev/disk2, use /dev/rdisk2
    • The code does this automatically!

  2. Larger block size:

    • macOS dd uses lowercase: bs=4m (not bs=4M)
    • The code handles this automatically!

  3. Disable Spotlight on USB:

    sudo mdutil -i off /Volumes/YOUR_USB

Safety Tips

⚠️ IMPORTANT - Before Flashing:

  1. Verify the disk identifier:

    diskutil info /dev/disk2

    Check that it says "external" and shows the correct size

  2. Double-check it's not your main drive:

    • /dev/disk0 is usually your Mac's internal drive
    • /dev/disk1 might be a recovery partition
    • USB drives are typically /dev/disk2 or higher

  3. Backup important data first!

    • Flashing will ERASE ALL DATA on the drive

Example Session

# 1. Test USB detection
$ python3 test_macos_usb.py
Current OS: Darwin
✓ Successfully imported USBManager
✓ Created USBManager instance
  - System: Darwin
  - is_macos: True
✓ Detection completed
  Found 1 USB device(s)

# 2. View detected devices
Detected Devices:
  Device 1:
    Path:       /dev/disk2
    Size:       32.0 GB
    Model:      SanDisk USB
    Mountpoint: /Volumes/COLDSTAR

# 3. Run the cold wallet system
$ python3 main.py
🔍 Detecting USB devices...
✓ Found 1 USB device(s)
✓ Selected device: /dev/disk2
✓ Using mounted volume: /Volumes/COLDSTAR

# Success!

Getting Help

If you encounter issues:

  1. Run the test script with verbose output
  2. Check that diskutil is working: diskutil list
  3. Verify Python version: python3 --version
  4. Check system logs if drives aren't appearing

Differences from Linux

Task Linux macOS
List disks lsblk diskutil list
Disk info fdisk -l diskutil info /dev/disk2
Mount mount /dev/sdb1 /mnt diskutil mount /dev/disk2s1
Unmount umount /mnt diskutil unmount /Volumes/USB
Eject eject /dev/sdb diskutil eject /dev/disk2
Format mkfs.ext4 /dev/sdb1 diskutil eraseDisk
Block size bs=4M bs=4m

The Python code handles all these differences automatically! 🎉