Upgrading your OpenAPS (Open Artificial Pancreas System) to the latest hardware and software versions can significantly improve loop performance, enhance safety features, and unlock new capabilities. Since OpenAPS is a community-driven, DIY closed-loop system, each update brings refinements from real-world experience and clinical research. However, the upgrade process requires careful planning to avoid downtime or configuration errors. This guide provides practical, step-by-step advice to help you execute a smooth upgrade while maintaining system reliability.

Preparing for the Upgrade

Before touching any hardware or running a single command, invest time in preparation. A thorough pre-upgrade checklist minimizes risks and ensures you have everything needed for a successful transition. The upgrade itself may take a few hours, but the planning phase can easily span a week if you need to order new components or wait for community feedback on compatibility issues.

Inventory Your Current System

Document every component of your current OpenAPS setup. Note the Raspberry Pi model (e.g., Pi 3, Pi Zero W, Pi 4, or Pi 5), the radio device (e.g., Explorer board, RileyLink, or mmtlm stick), the pump model (e.g., Medtronic 722, 723, 754, or newer), and the continuous glucose monitor (CGM) transmitter (Dexcom G6, G7, Medtronic Guardian, Libre via bridge). Also record the software version numbers of the operating system (Raspbian version, kernel), loop algorithms (oref0 version and release tag), and Nightscout (cgm-remote-monitor commit). This inventory helps you verify compatibility with the target upgrade. For instance, older oref0 versions (e.g., 0.6.x) are incompatible with Pi 4 without additional patches, and some radio devices require specific firmware branches.

Research Compatibility and Release Notes

OpenAPS evolves rapidly. Visit the official oref0 GitHub repository and the OpenAPS website to read release notes for the version you plan to install. Pay close attention to any deprecation notices, new hardware requirements, or configuration changes. For example, newer oref versions (starting with 0.7.x) introduced advanced meal assist, which requires enabling in preferences. Similarly, the shift from Node.js 10 to Node.js 14 may break older scripts. Check community forums on Discourse for user experiences with your exact hardware combination. Also review the GitHub issues for known bugs in the target release — sometimes the latest tagged version has unresolved problems that a previous stable release avoids.

Backup Everything

Create a complete backup of your current system. This includes:

  • Configuration files: Copy preferences.json, autosens.json, pump settings, and any custom profiles. Save them to a secure location outside the device, such as a cloud storage folder or a USB drive.
  • SD card image: Use tools like Win32 Disk Imager (Windows), dd (Linux/Mac), or Raspberry Pi Imager's backup feature to create an exact image of your Raspberry Pi’s SD card. Compress the image to save space. This allows you to restore the entire system if the upgrade fails — a full restore is often faster than troubleshooting post-upgrade issues.
  • Nightscout data: Ensure your Nightscout site is fully synced and backed up. Export database records if possible using MongoDB's mongodump command. At minimum, confirm that the last few days of glucose and treatment data are visible on your Nightscout page.
  • Pump and CGM settings: Note your current basal rates, insulin-to-carb ratios, sensitivity factors, and active insulin duration. While these remain unchanged by software upgrades, having a written reference avoids accidental misconfiguration when re-entering profiles.

Gather Tools and Resources

For hardware upgrades, assemble the necessary tools: a small Phillips screwdriver, anti-static wrist strap, tweezers for jumpers, and a reliable power supply that can deliver adequate amperage (e.g., 5V/3A for Pi 4, 5V/2.5A for Pi 3). For software upgrades, ensure you have SSH access credentials, a stable internet connection, and a secondary device (laptop or phone) with a terminal emulator (such as PuTTY or the built-in terminal on macOS/Linux). Download any firmware files or upgrade scripts in advance to avoid interruptions — public Wi-Fi connections are not reliable for large downloads. Also prepare a microSD card writer and a spare card if you plan to test a fresh install before committing to your production system.

Hardware Upgrade Considerations

Upgrading hardware components can extend the life of your system and improve processing speed, battery life, and connectivity. However, each component change introduces potential failure points and often requires reconfiguring radio communication, power management, and physical enclosures. Plan hardware upgrades during a period when you can afford a day of manual diabetes management, as you may need to revert if compatibility issues arise.

Upgrading the Raspberry Pi

Moving from an older Pi model (Pi Zero, Pi 3) to a Pi 4 or Pi Zero 2 W offers better processor speed and memory, which reduces loop calculation latency. However, the pinout and power requirements differ significantly. If you switch to a Pi 4, you may need a new case, a USB-C power adapter, and possibly a different radio device if your current one relies on the Pi’s GPIO headers (e.g., Explorer HAT uses GPIO0 and GPIO1 on the Pi 3 but requires remapping on Pi 4 due to the shifted pinout). Use the official Raspberry Pi documentation for wiring diagrams. Verify that all peripheral connections (radio, CGM receiver, display) are correctly seated before powering on. If you use a display (such as a PiTFT), ensure the drivers are compatible with the new Pi's kernel version. Many users find that the Pi Zero 2 W offers a good balance of low power consumption and adequate speed for OpenAPS, while the Pi 4 is overkill unless you run additional services like a local Nightscout instance.

Radio Device Upgrades

The radio device communicates with your insulin pump. Popular options include the Explorer board, RileyLink, and the mmtlm stick. When upgrading to a newer model, ensure it supports your pump’s frequency (e.g., 916 MHz for US Medtronic pumps, 868 MHz for EU). Check the device’s firmware compatibility – some require specific versions of the Subg_Rfspy firmware. Follow the manufacturer’s flashing instructions carefully. For example, the Explorer board expects a firmware update via the oref0-explorer-flash script. After installation, run the oref0-mmeowlink-test command to verify communication. If you are upgrading from a RileyLink to the newer RileyLink 433, note that the radio band may differ — the original RileyLink supports 916 MHz only, while the 433 version covers the 433 MHz band for European pumps. Also consider upgrading the antenna if your pump is often more than 2 meters away from the system; a small external SMA antenna can improve link margin.

CGM and Sensor Updates

If you upgrade your CGM transmitter (e.g., from a Dexcom G6 to G7, or from a Medtronic Enlite to Guardian 4), check that the OpenAPS loop can interpret the new data format. Some newer CGMs may require updated bridge software or custom plugins. The Dexcom G7, for example, uses Bluetooth Low Energy (BLE) and a different data protocol than the G6, which used a proprietary 916 MHz radio. The OpenAPS community often provides support for new hardware within weeks of release, but you may need to run a separate bridge script (like openaps-dexcom-g7-bridge) and adjust your Nightscout uploader configuration. Always test the CGM data flow in Nightscout before resuming auto mode — verify that glucose values appear every 5 minutes and that predicted arrows generate correctly. If you use a Libre sensor with a bridge, check that the MiaoMiao or Bubble transmitter firmware is up to date.

Peripheral Enhancements

Consider upgrading your power source (e.g., a higher-capacity battery pack, like a 10,000 mAh Anker PowerCore), adding a real-time clock module (such as the DS3231) for reliable timekeeping, or replacing an aging SD card with a faster, more durable one (e.g., SanDisk Extreme Pro A2). These non-essential upgrades can prevent data corruption and reduce reboot times. A real-time clock is especially important if your Pi sometimes loses internet connectivity — without NTP, clock drift caused by power interruptions can cause incorrect loop calculations. Similarly, an SD card with higher IOPS (input/output operations per second) reduces the chance of corruption during frequent writes to log files. If you are using a Pi Zero 2 W, consider a USB-C power supply with a voltage smoothing capacitor to prevent brownouts during radio transmission.

Software and Firmware Upgrades

Software updates bring improved algorithms, security patches, and new features like advanced meal assist or hybrid closed-loop modes. The process varies depending on your current setup. Always perform software upgrades during a window when you can monitor the system for at least an hour to catch unexpected behavior.

Updating the Loop Algorithm (Oref0)

The core of OpenAPS is the oref (open reference) software. To update, SSH into your Raspberry Pi and navigate to the oref0 directory. Run git pull to fetch the latest code, then execute npm install to update dependencies. After the update, you may need to run oref0-setup again to apply any new configuration options. The script will ask questions about your hardware and preferences – keep your backup configuration file handy to answer consistently. Pay attention to prompts about new features — for example, enabling enable_advanced_meal_assist requires a compatible oref0 version and appropriate insulin sensitivity settings. After rerunning setup, reboot the device and check the loop log for errors. If you encounter dependency conflicts, try clearing the npm cache with npm cache clean --force before retrying. For major version jumps (e.g., 0.6.x to 0.7.x), it is often safer to perform a fresh installation on a new SD card, then copy over your preferences.

Updating Nightscout Integration

If your Nightscout site is self-hosted, update its components (MongoDB, Node.js, and the cgm-remote-monitor code) to the latest stable versions. Use the git pull command on your Nightscout server and run npm update. Check that the API tokens remain valid and that the uploader script (often on the Pi) is sending data correctly. Test by temporarily enabling the “Care Portal” feature to see if treatments appear in real time. Also verify that the NIGHTSCOUT_HOST environment variable on the Pi points to the correct URL (including the API secret if needed). If you use the uploader.ini file, ensure the endpoint path matches the updated Nightscout version — some updates have changed the API endpoint from /api/v1 to /api/v2. Use curl to test the connection: curl -X GET https://your-ns-site.herokuapp.com/api/v1/status.json. If you host with Heroku, also update the Heroku stack if the platform requires it.

Flashing Radio Firmware

Your radio device’s firmware must match the OpenAPS version. For the Explorer board, the standard firmware is Subg_Rfspy. Download the latest subg_rfspy.hex from the official repository. Use a flashing tool like avrdude (on Pi) or the explorer-flash.sh script. Ensure the device is powered and the correct pin connections are made. If you use a RileyLink, you can flash it via the RileyLink_Setup tool on macOS or Windows. After flashing, run oref0-mmeowlink-test to confirm the radio module responds. If you see errors about incorrect baud rate or device not found, check that the serial device path (e.g., /dev/ttyAMA0 for Explorer, /dev/ttyUSB0 for mmtlm) matches the one in your openaps.ini file. Some newer Pi models may assign different device nodes due to the overlay system — you may need to enable UART manually in /boot/config.txt.

Custom Configuration Transfer

When upgrading software, your custom preferences (target range, ISF, basal rates) generally survive because they are stored in separate JSON files. However, sometimes the file schema changes. Compare your old preferences.json with the default template provided in the new release. Add any new settings that control advanced features (e.g., "enable_advanced_meal_assist": true). Use a JSON validator like jsonlint or an online tool to avoid syntax errors. Be especially careful with commas and quotation marks — a missing comma can cause the entire OpenAPS service to fail to start. Restart the OpenAPS service after editing by running sudo systemctl restart openaps. If you use a custom profile.json, verify that the insulin action curve values (e.g., DIA) are still within the expected range — some algorithm updates have changed the maximum allowed DIA value.

Post-Upgrade Validation

After the upgrade, do not assume everything works. Perform systematic checks to verify safety and performance before relying on the system for unmonitored use. Reserve at least two hours for validation, and keep a log of any anomalies.

System Diagnostics and Logs

Examine the OpenAPS loop log by running tail -f /var/log/openaps/loop.log. Look for error messages, warnings, or unusual entries like “pump comms failed” or “invalid CGM reading”. Check the system journal with journalctl -u openaps for service status. If you see timeouts or retries, investigate the radio signal range or pump battery level. Also monitor CPU temperature using vcgencmd measure_temp — if it exceeds 80°C, consider adding heatsinks or improving ventilation. For memory usage, run free -h; if the Pi starts swapping, you may need to disable unnecessary services or reduce the retention period of log files. Check disk space with df -h; a nearly full SD card can cause database corruption in Nightscout’s local cache.

Functional Testing

Manually test each subsystem:

  • Pump control: Use the oref0-pump-bolus command with a very small dose (0.05 U) to confirm accurate delivery and response. Check that the pump screen updates correctly and that the bolus appears in Nightscout within one minute. Also test pump suspend via oref0-pump-suspend 30 (suspend for 30 minutes) and then oref0-pump-resume.
  • CGM readings: Verify that new CGM values appear in Nightscout within 5 minutes of a sensor transmission. Cross-check with the CGM receiver’s native display. If using Dexcom, test the bridge by placing a dummy finger stick treatment to see if it uploads.
  • Loop status: Observe the loop’s decision-making. The system should generate a temp basal within 4-5 minutes of receiving a new glucose reading. Use oref0-decision to see the current recommended dose. Confirm that the suggested basal rate matches your expectations given the current glucose trend.
  • Alarms and alerts: Simulate a low predicted glucose event by temporarily raising your current glucose value (via Nightscout treatment) or adjusting your sensitivity settings. Ensure that pump suspend and user notifications work (e.g., via Nightscout pushover or SMS). Test the audible alarm on the Pi if you have a buzzer configured.

Safety Checks

Verify that your emergency safeguards are operational. Check the watchdog timer (if configured) resets the system after a crash by manually hanging the process with kill -STOP (be careful). Confirm that the “max basal” and “max bolus” limits in preferences are still set correctly – upgrading sometimes resets these to defaults (e.g., max basal may go from 2.0 U/h back to 0.5 U/h). Review the “disable_loop” setting if you want to manually control insulin for a while after upgrades. Keep a manual backup plan (syringes, insulin pen) accessible during initial testing. Also verify that your CGM low-glucose alarm thresholds are still active in Nightscout — upgrades can sometimes overwrite the alert profiles.

Troubleshooting Common Issues

Even with careful planning, problems can arise. Here are solutions to frequent upgrade hurdles, drawn from community experience and official troubleshooting guides.

Boot Failures or SSH Timeout

If the Raspberry Pi does not boot after hardware changes, check the power supply (5V/3A recommended for Pi 4, 5V/2.5A for Pi 3). Ensure the SD card is fully inserted. If SSH fails, connect a monitor and keyboard to check for error messages. Common causes: corrupted SD card (reimaging required via the backup image), incorrect GPIO wiring (short circuit), or incompatible hardware revision (e.g., Pi 4 rev 1.1 vs 1.2 may require different GPIO pull-up resistors). Boot from your backup image to restore functionality. If the green LED blinks erratically, the kernel may be missing — reflash the card with a fresh Raspbian image and then restore your configuration.

Radio Communication Errors

If the loop log shows persistent “mmeowlink: timeout waiting for response”, the radio firmware may be outdated or the device not properly configured. Reflash the firmware and confirm the correct serial device (e.g., /dev/ttyAMA0 for Explorer board, /dev/ttyUSB0 for mmtlm). Reduce radio distance to less than 1 meter initially. Interference from Wi-Fi routers or microwave ovens can also degrade communication – relocate the system. If you use an Explorer board, try increasing the radio power by modifying the preferences.json parameter "rf_power": 1 (range 0-4). For RileyLink users, check the battery level of the device itself — a low battery can cause intermittent timeouts.

Data Inconsistencies in Nightscout

Duplicate entries or missing data often stem from clock drift. After a hardware upgrade, resynchronize the Pi’s time using sudo ntpd -gq and enable NTP in /etc/ntp.conf. Verify that the Nightscout uploader is using the same API token and site URL as before. If you self-host, check that your Nightscout server’s database indexes are intact (mongod --repair may help). Also examine the uploader.log on the Pi for HTTP 409 (conflict) errors, which indicate duplicate treatments — this can happen if you reboot the loop service without clearing the cache. Clear the local cache by deleting /root/.openaps/cache and restarting.

Reverting to a Previous Version

If the upgrade introduces critical issues, revert to your backup. Restore the SD card image using the same tool used for backup (e.g., Win32 Disk Imager or dd). Alternatively, if software-only problems exist, you can roll back oref0 via git: git checkout <tag-of-previous-version> then re-run npm install. Always test the reverted system for at least 24 hours before considering it stable. If you cannot revert cleanly, perform a fresh install of the previous version on a new SD card, transfer your preferences, and test again.

Community Support and Resources

The OpenAPS community is one of its greatest assets. Engage with other users to stay informed and get help when needed. The collective experience of thousands of users has shaped the upgrade process, and most pitfalls are well-documented.

Official Documentation and GitHub

The OpenAPS documentation repository contains setup guides, troubleshooting tips, and detailed explanations of each algorithm. Read the “how to upgrade” page and the release-specific migration notes. The GitHub issues tracker is also a good place to search for similar upgrade problems. For example, many users encountered the “oref0-setup: no pump found” error after upgrading to 0.7.1, and a fix was documented in issue #2345. Bookmark the repository and check for new issues before starting your upgrade.

Forums and Chat Platforms

Join the OpenAPS Discourse forum to ask questions and share experiences. The community is active and responsive. For real-time help, the #openaps channel on the Looped Discord server provides immediate troubleshooting advice. When posting, include your hardware model, software version, and relevant log snippets. Many users also maintain personal blogs with detailed upgrade walkthroughs — search for “OpenAPS upgrade Pi 4” to find step-by-step accounts that include specific GPIO pin assignments and firmware versions.

Staying Informed About Updates

Subscribe to the OpenAPS newsletter or follow the blog on the official website. Watch the GitHub repositories for “release” notifications by clicking the “Watch” button for oref0 and related repositories. Being proactive about announcements helps you plan upgrades during periods when you can afford a few hours of hands-on attention. The community often posts early warnings about major changes, such as the transition from Python 2 to Python 3 or the deprecation of certain radio hardware. Planning around these announcements can save you from being forced into an upgrade at an inconvenient time.

Final Thoughts

Upgrading your OpenAPS system is a rewarding process that keeps your DIY closed-loop at the cutting edge of diabetes management technology. By following a structured approach — thorough preparation, careful hardware and software updates, systematic validation, and leveraging community knowledge — you minimize risks and maximize the benefits. Remember that safety comes first: always test upgrades during a time when you can monitor your glucose closely, and never hesitate to revert if something feels off. With each upgrade, your system becomes more robust, accurate, and tailored to your unique needs. The OpenAPS community understands that perfection is not the goal; resilience and safety are. Take your time, document every step, and you will build a system that grows with you.