⚠️ BREAKING CHANGE: Dev Branch Repository Reorganization - Manual Migration Required

[ggilestro]

Overview

Important: The latest dev branch updates (pushed today) introduce a major repository reorganization that will break existing installations on both nodes and ethoscope
devices. Manual intervention is required to migrate to the new unified directory structure.

What Changed

• Old Structure: Separate directories /opt/ethoscope-device and /opt/ethoscope-node
• New Structure: Unified directory /opt/ethoscope with organized subdirectories:
  • /opt/ethoscope/src/ethoscope/ (device code)
  • /opt/ethoscope/src/node/ (node code)
  • /opt/ethoscope/src/updater/ (updater tools)
  • /opt/ethoscope/scripts/ (service files)

Who Is Affected

• ✅ New installations: No action needed
• ⚠️ Existing node installations: Migration script required
• ⚠️ Existing ethoscope devices: Manual migration required

---

🖥️ Node Migration (Automated)

For node installations, we provide an automated migration script:

Migration Steps

1. Pull the latest dev branch:
   cd /opt/ethoscope-node
   sudo git pull origin dev
2. Run the migration script:
   sudo /opt/ethoscope-node/accessories/upgrade_scripts/migrate_to_unified_structure.sh --auto
3. Verify the migration:
   sudo systemctl status ethoscope_node
   sudo systemctl status ethoscope_backup
   sudo systemctl status ethoscope_update_node

What the Script Does

• Stops running services
• Moves /opt/ethoscope-node → /opt/ethoscope
• Updates systemd service file links
• Installs Python packages in development mode
• Enables and restarts services

---

📱 Ethoscope Device Migration (Manual)

For ethoscope devices, follow this manual procedure:

Migration Steps

1. SSH into the ethoscope device:
   ssh alarm@ethoscope001.local # Replace 001 with your device number

Password: alarm

2. Pull latest changes and run migration:
   cd /opt/ethoscope-device && sudo git pull
   sudo /opt/ethoscope-device/accessories/upgrade_scripts/migrate_to_unified_structure.sh --auto && exit
3. Your ethoscope should appear on the node again

What This Does

• Pulls the latest dev branch with reorganized structure
• Runs the automated migration script
• Moves /opt/ethoscope-device → /opt/ethoscope
• Updates service files and restarts services
• Exits automatically when complete

---

🛠️ Troubleshooting

Migration Script Issues

• Check current state: sudo /path/to/migrate_to_unified_structure.sh --check
• View script help: sudo /path/to/migrate_to_unified_structure.sh --help

Service Issues

• Check service status: sudo systemctl status <service_name>
• View service logs: sudo journalctl -u <service_name> -f
• Restart services: sudo systemctl restart <service_name>

If Migration Fails

1. Check error messages in the migration script output
2. Ensure you have sufficient disk space
3. Verify network connectivity for package installations
4. Report issues with full error logs

---

🔄 Post-Migration

After successful migration:

1. Verify all services are running
2. Test ethoscope functionality (web interface, tracking, etc.)
3. Update any custom scripts that reference old paths
4. The old directories are now symlinks for backward compatibility

---

📝 Technical Details

• Python package installation now uses modern pyproject.toml structure
• Service files moved to /opt/ethoscope/scripts/
• Improved updater with better error handling and node self-update support
• Backward compatibility maintained through symlinks

---

🚨 Important Notes

• ⚠️ This is a one-way migration - backup your data before proceeding
• ⏱️ Services will be temporarily stopped during migration
• 🔗 Custom scripts referencing old paths should continue working via symlinks
• 📧 Report issues with full error logs for faster resolution

---

Questions or Issues? Please open a GitHub issue with:

• Your installation type (node/device)
• Full error messages
• System information (uname -a, Python version)
• Migration script output