# Web3 Pi Web3 Pi documentation — running Ethereum nodes on Raspberry Pi, and the Web3 Pi UPS smart DC uninterruptible power supply. # Web3 Pi # Web3 Pi documentation This documentation provides everything you need to get started with Web3 Pi.\ Find step-by-step guides for setup, detailed explanations of features, monitoring tools, troubleshooting and tips for running your Ethereum node smoothly on Raspberry Pi. [Get Started](/setup/prerequisites) ## Learn Learn more about the Web3 Pi project and benefits of running an Ethereum node on a Raspberry Pi. - About Web3 Pi ______________________________________________________________________ Essential information before starting your Web3 Pi journey [The Web3 Pi Project](https://docs.web3pi.io/introduction/web3-pi-project/index.md) - Running an Ethereum Node ______________________________________________________________________ Learn about the benefits of running your very own Ethereum node on a Raspberry Pi [What is an Ethereum Node?](https://docs.web3pi.io/introduction/ethereum-node/index.md) ## Setup & Configuration Get started with running your very own Ethereum node on a Raspberry Pi. - **Prerequisites** ______________________________________________________________________ Hardware and software requirements to run an Ethereum node on a Raspberry Pi [Prerequisites](https://docs.web3pi.io/setup/prerequisites/index.md) - **Setup Guide** ______________________________________________________________________ A complete step-by-step guide to setting up your own Ethereum node on a Raspberry Pi using Web3 Pi [Setup guide](https://docs.web3pi.io/setup/supported-configurations/index.md) ## Monitoring & Management Tips and tricks to keep your node running smoothly. - **Monitoring** ______________________________________________________________________ Learn how to monitor your node [Managing your node](https://docs.web3pi.io/monitoring/index.md) - **Management** ______________________________________________________________________ Learn how to manage and maintain your node [Managing your node](https://docs.web3pi.io/management/index.md) - **Troubleshooting** ______________________________________________________________________ Learn how to troubleshoot common issues [Troubleshooting](https://docs.web3pi.io/support/troubleshooting/index.md) # What is an Ethereum Node? Before running your own Ethereum node using Web3 Pi or any other method, it's important to understand what a node is and its role in the Ethereum network. ## The Basics An Ethereum node is simply a piece of software that connects to the Ethereum network. It downloads a copy of the Ethereum blockchain and follows the network's consensus rules to verify transactions and blocks. Running a node contributes to the decentralization, security, and resilience of the Ethereum network. For a comprehensive overview, start by reading the documentation provided by the Ethereum Foundation: - [Running an Ethereum Node Overview](https://ethereum.org/en/run-a-node/) ## Node Components: Execution and Consensus Clients A modern Ethereum node consists of **two main software components** running together: 1. **Execution Client (EL):** Sometimes called the Execution Engine or formerly Eth1 client, this software listens for new transactions broadcasted to the network, executes them in the Ethereum Virtual Machine (EVM), and holds the latest state and database of all Ethereum data. It handles the "computation" part of the network. 1. **Consensus Client (CL):** Also known as the Beacon Node or formerly Eth2 client, this software implements the proof-of-stake consensus algorithm. It enables the network to agree on the state of the blockchain based on the validated data received from the Execution Client. It handles the "agreement" part of the network. These two clients work in tandem to keep the node synchronized with the head of the Ethereum chain and allow users to interact with the network. Learn more about clients and nodes: - [Nodes and Clients Documentation](https://ethereum.org/en/developers/docs/nodes-and-clients/) ## Why Run a Node? People run Ethereum nodes for various reasons: - **Support the Network:** Increase the decentralization and security of Ethereum. - **Trustless & Uncensored Access:** Interact directly with the Ethereum blockchain without relying on third-party services, ensuring privacy and avoiding potential censorship or rate limits. - **High-Performance RPC:** Gain fast, local, and unlimited access to the Ethereum RPC API for wallets and applications. - **Development:** Provide a local endpoint for developing and testing decentralized applications (dApps). - **Foundation for Staking:** Provide the necessary infrastructure (EL/CL clients) that *could* be configured for staking. It is important to clarify: **running an Ethereum node does not require staking 32 ETH.** Anyone can run a full node using Web3 Pi to verify transactions, interact privately with the blockchain, and contribute to network health without any ETH deposit. Staking, which does require 32 ETH per validator, is a separate activity that involves proposing and attesting to new blocks to earn rewards. What about staking? While running a node is a prerequisite for staking, configuring it specifically for staking duties is a complex process that goes beyond the standard Web3 Pi setup. [You can learn more about staking here.](https://docs.web3pi.io/introduction/staking/index.md) # Next Steps Now that you have a basic understanding of Web3 Pi and Ethereum nodes, here's how to proceed: ## 1. Make Key Decisions Before you begin the setup process, you need to decide on a few things: ### Single or Dual Device Mode? An Ethereum node requires both an Execution Client (EL) and a Consensus Client (CL). - **Single Device:** Run both EL and CL clients on one Raspberry Pi. This is cheaper but shares resources. A **Raspberry Pi 5** with **8GB RAM** is recommended for this configuration. - **Dual Device:** Run the EL client on one Raspberry Pi and the CL client on a separate Raspberry Pi. This allows you to use two, weaker devices in place of one, more powerful one, at the cost of increased complexity. If you're unsure, we recommend starting with a single device setup. ## 2. Prepare Your Hardware Ensure you have all the necessary hardware components (Raspberry Pi, power supply, storage, network cable, etc.). ### Use Your Own Hardware or the WelcomeBox? - [**WelcomeBox:**](https://docs.web3pi.io/welcome-box/index.md) Web3 Pi offers a WelcomeBox — an all-in-one solution with pre-selected, compatible hardware to help you get started quickly. - **Own Hardware:** You can use your existing Raspberry Pi (Model 4, 5, or CM4) and compatible peripherals. Ensure you have everything required by checking the [Prerequisites Guide](https://docs.web3pi.io/setup/prerequisites/index.md) and the [Hardware Recommendations](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/index.md) document. ### Optional LCD Display? - You can add an optional LCD display to your setup for at-a-glance monitoring. It's included in the WelcomeBox and natively supported by the Web3 Pi system — just plug it in, no installation or configuration needed.\ Details are in the [LCD Monitoring Guide](https://docs.web3pi.io/monitoring/lcd/index.md). ## 3. Set Up Your Node - Follow the **[Full Setup Guide](https://docs.web3pi.io/setup/supported-configurations/index.md)** relevant to your configuration for detailed, step-by-step instructions assembling the hardware and booting your Raspberry Pi for the first time. ## 4. Manage Your Node Web3 Pi includes a set of tools to help you manage and monitor your node: - The **[Grafana Dashboard](https://docs.web3pi.io/monitoring/grafana/index.md)** provides real-time monitoring of your node's performance. - The **[Cockpit Dashboard](https://docs.web3pi.io/management/cockpit/dashboard/index.md)** provides an overview of your node's status and allows you to manage basic settings. - The **[Web3 Pi Updater](https://docs.web3pi.io/management/cockpit/web3-pi-updater/index.md)** allows you to upgrade your node's ethereum dependencies and other software. - The **[Web3 Pi Link](https://docs.web3pi.io/management/cockpit/web3-pi-link/index.md)** allows you to access your node from anywhere in the world. Warning Remember: Staking configuration is currently considered an advanced, unsupported procedure. Proceed with extreme caution if exploring this path independently. # Can I Earn with Web3 Pi? Warning Running an Ethereum validator involves significant financial risk and technical responsibility. You do so entirely at your own risk. Running a standard Ethereum node with Web3 Pi does not directly generate income by itself. Its primary purpose is providing secure, private, and performant access to the blockchain. However, Web3 Pi serves as a foundation for potential earning opportunities: - **Solo Staking:** While running a node doesn't require 32 ETH, staking to secure the network and earn rewards does. Web3 Pi hardware (like Raspberry Pi 5) is capable of handling staking duties (proven in tests running 200 validators), although the setup currently requires manual configuration. We aim to simplify this process significantly in the future. - **RPC Monetization:** Through collaborations like the one with Golem Network, there are plans to allow Web3 Pi node operators to share RPC endpoint and potentially earn rewards (e.g., in GLM tokens) for serving requests. This feature is not yet available. If you are considering staking, it is crucial that you thoroughly research and understand the process, responsibilities, and significant risks involved before attempting it. **Learn more about staking fundamentals: - [Ethereum Staking Guide](https://ethereum.org/en/staking/)** # Web3 Pi: Before you start ## The Web3 Pi Project Web3 Pi is an open-source project simplifying the operation of a personal Ethereum node using Raspberry Pi devices. We provide a ready-to-use, optimized operating system image and automated tools, making node ownership accessible even without deep technical knowledge. Leveraging the Raspberry Pi's efficient ARM architecture, Web3 Pi ensures reliable blockchain access with very low energy consumption (around 8W), allowing for cost-effective, 24/7 operation. Our goal is to lower the barrier to entry for direct participation in the Ethereum network. Currently supported devices (at least 8GB RAM required): - [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) - [Raspberry Pi 4](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) - [Raspberry Pi CM4/CM5](https://www.raspberrypi.com/products/compute-module-5/) ## Why Web3 Pi? Web3 Pi images offer several advantages for setting up your Ethereum node: - **Plug & Play:** Simply flash the image to your storage and power up the Raspberry Pi. - **Solid Foundation:** Based on Ubuntu 24.04 LTS for ARM64, providing long-term support. - **Automated Setup:** Handles initial configuration for network, user accounts, etc. - **Disk Management:** Automatically partitions and formats attached storage. - **Auto-Sync:** Automatically starts the Ethereum sync process. - **Easy Updates:** Includes an APT repository for straightforward installation and upgrades. - **Monitoring Included:** Comes with pre-configured monitoring dashboards. - **Security Focused:** Includes the UFW firewall configured for basic security. ## Why Raspberry Pi? Raspberry Pi devices are an excellent platform for running an Ethereum node (Full or Archive) due to several key factors: - **Affordable:** Set up a Full Ethereum node (EL/CL) for under $350. - **Efficient:** As a dedicated device, resources are focused solely on running the node. - **Low Power Consumption:** Typically consumes around 8W. - **Small Form Factor:** Its compact size makes it easy to place anywhere in your home. - **Ideal for 24/7 Operation:** The combination of low cost, low power, and small size makes it perfect for continuous operation. What now? - [Learn what exactly is an Ethereum node and how it works](https://docs.web3pi.io/introduction/ethereum-node/index.md) (next step). - [Get started with running your own Ethereum node on a Raspberry Pi](https://docs.web3pi.io/introduction/next-steps/index.md). # Web3 Pi: Hardware Assembly (Dual-Device Mode) Assembling the hardware for a dual-device Web3 Pi node involves building **two separate Raspberry Pi systems**: one designated as the **Execution Layer (EL) Node** and the other as the **Consensus Layer (CL) Node**. While the assembly steps for *each individual device* are identical to the [Single-Device Hardware Assembly Guide](https://docs.web3pi.io/setup/single-mode/hardware-assembly/index.md), managing two builds requires careful attention, especially regarding component placement (SSDs) and labeling. Follow Instructions Carefully Read through these instructions and the single-device guide before starting. Ensure you have all components for **both** devices laid out and organized. ## Before You Start 1. **Gather Components:** Ensure you have all the necessary hardware components for **two complete Raspberry Pi setups** as outlined in the [Dual-Device Hardware Checklist](https://docs.web3pi.io/setup/dual-mode/hardware-checklist/index.md) and [Recommendations](https://docs.web3pi.io/setup/dual-mode/hardware-recommendations/index.md). This includes two Pis, two power supplies, two enclosures/cooling solutions, two microSD cards, and two SSDs (one 2TB+, one 256GB+). 1. **Prepare SD Cards:** You should have already flashed **two separate microSD cards** using the Web3 Pi Imager in Dual-Device mode – one configured for the EL node and one for the CL node. Keep them clearly identifiable. 1. **Reference Guide:** Keep the [Single-Device Hardware Assembly Guide](https://docs.web3pi.io/setup/single-mode/hardware-assembly/index.md) open in another tab or window. You will follow those detailed steps *twice*, once for each device. ## Assembly Steps ### Step 1: Decide and Label Your Devices (Crucial!) Before assembling anything, decide which Raspberry Pi will be your EL Node and which will be your CL Node. Label Everything Clearly Use sticky notes, labels, or markers to clearly label each Raspberry Pi board, enclosure/case, and the corresponding EL and CL microSD cards. This labeling will prevent you from inserting the wrong SD card or SSD into the wrong device. ### Step 2: Assemble the Execution Layer (EL) Node 1. Take the Raspberry Pi and enclosure you designated as the **EL Node**. 1. Follow the **detailed steps** outlined in the [Single-Device Hardware Assembly Guide](https://docs.web3pi.io/setup/single-mode/hardware-assembly/index.md) precisely. 1. **Critical Check - SSD:** When you reach the step to install the storage drive, ensure you install the **larger (2TB or greater) SSD** into this EL Node device. 1. **Critical Check - SD Card:** When you reach the step to insert the microSD card, ensure you insert the card specifically flashed and labeled for the **EL Node**. 1. Complete the assembly for the EL Node as per the single-device guide. ### Step 3: Assemble the Consensus Layer (CL) Node 1. Take the Raspberry Pi and enclosure you designated as the **CL Node**. 1. Follow the **detailed steps** outlined in the [Single-Device Hardware Assembly Guide](https://docs.web3pi.io/setup/single-mode/hardware-assembly/index.md) precisely, just as you did for the EL node. 1. **Critical Check - SSD:** When you reach the step to install the storage drive, ensure you install the **smaller (256GB or greater) SSD** into this CL Node device. 1. **Critical Check - SD Card:** When you reach the step to insert the microSD card, ensure you insert the card specifically flashed and labeled for the **CL Node**. 1. Complete the assembly for the CL Node as per the single-device guide. ### Step 4: Final Check You should now have two fully assembled Raspberry Pi devices: - One labeled "EL Node" containing the larger SSD and the EL microSD card. - One labeled "CL Node" containing the smaller SSD and the CL microSD card. Double-check your labels and component placement one last time. #### Hardware connections Once you have both devices assembled, connect them as follows: Warning For the mDNS mechanism to work, both devices must be connected to the same local network. It's recommended to use one network switch for both devices. Refer to the following image to verify your setup: Ensure all cables and storage devices are securely connected before proceeding. ## Next Steps With both devices assembled correctly, you are ready to connect them to your network and begin the software installation and synchronization process. ## Dual Device Node Requirements Suggested configurations: - 2 X Raspberry Pi 5 - 2 X Raspberry Pi 4 - 1 X Raspberry Pi 5 + 1 X Raspberry Pi 4 or any other combination, including CM4. The default setup requires the following hardware components: - 2 x Raspberry Pi (8GB) starter kits - 2 x SSD (one for each device) - 1 x SD Card reader/writer - 2 x Fast microSD Card Optionally, you can add an [LCD display](https://docs.web3pi.io/monitoring/lcd/index.md) to each Raspberry Pi for monitoring purposes. A device with an execution client needs 2TB+ fast storage. A device with a consensus client needs 256GB+ fast storage. ### Raspberry Pi You can use: - [Raspberry Pi 5](https://botland.store/raspberry-pi-5-modules-and-kits/23905-raspberry-pi-5-8gb-5056561803326.html) with [Active cooling](https://botland.store/raspberry-pi-5-mounting-elements/23925-raspberry-pi-active-cooler-heatsink-fan-for-raspberry-pi-5-5056561803357.htm) - [Raspberry Pi 4](https://botland.store/raspberry-pi-4b-modules-and-kits/16579-raspberry-pi-4-model-b-wifi-dualband-bluetooth-8gb-ram-18ghz-5056561800356.html) with [Active cooling](https://botland.store/raspberry-pi-4b-cases/15106-case-justpi-for-raspberry-pi-4b-aluminum-with-dual-fan-black-lt-4b02-5903351242660.html) - [Raspberry Pi CM4](https://botland.store/raspberry-pi-cm/18211-raspberry-pi-cm4-compute-module-4-8gb-ram-32gb-emmc-wifibluetooth-cm4108032-5904422368593.html) with [Active cooling](https://botland.store/raspberry-pi-cm/21716-dedicated-all-in-one-3007-cooling-fan-for-raspberry-pi-cm4-waveshare-22096.html) and motherboard Note **8GB** RAM is required. # Web3 Pi: Recommended Hardware In a dual-device setup, the workload of running an Ethereum node is split between two Raspberry Pi devices. One device runs the **Execution Layer (EL) client** (like Geth), which requires significant storage, while the other runs the **Consensus Layer (CL) client** (like Nimbus or Lighthouse), which has much lower storage needs but still benefits from fast access. This setup requires **two complete Raspberry Pi systems**, each with its own Pi, power supply, storage, SD card, and cooling/enclosure. Supported combinations include: - Two Raspberry Pi 5 - Two Raspberry Pi 4 - One Raspberry Pi 5 and one Raspberry Pi 4 - Any combination including Compute Module 4/5 ## Raspberry Pi Models You will need **two** Raspberry Pi devices. The following models are supported: - **Raspberry Pi 5:** Recommended for best performance, especially for the EL client. - **Raspberry Pi 4 Model B:** A viable option, particularly suitable for the CL client or if cost is a major factor. Can also run the EL client, though sync times may be longer than Pi 5. - **Raspberry Pi Compute Module 4 (CM4):** Requires a compatible carrier board with necessary ports (Ethernet, USB, potentially PCIe/M.2) and a cooling solution. RAM Requirement Regardless of the model chosen, **both** Raspberry Pi devices **must have at least 8GB of RAM**. Refer to the hardware checklists for specific model links: - [Single Device Checklist (useful for Pi links)](https://docs.web3pi.io/setup/single-mode/hardware-checklist/index.md) - [Dual Device Checklist](https://docs.web3pi.io/setup/dual-mode/hardware-checklist/index.md) ## SSD Drive Requirements - **Execution Client (EL) Device:** Needs a **2 TB or larger** fast SSD (NVMe or USB 3.0) to store the growing Ethereum blockchain state data. - **Consensus Client (CL) Device:** Needs a **500 GB or larger** fast SSD. While 500GB is sufficient currently. NVMe or a reliable USB 3.0 SSD is recommended. ### Connection Options - **Raspberry Pi 5:** - External USB 3.0 SSD drive. - M.2 NVMe drive with an NVMe HAT (connects via PCIe). - M.2 NVMe drive with a USB 3.0 to M.2 adapter. - **Raspberry Pi 4 / CM4 (with appropriate carrier board):** - External USB 3.0 SSD drive. - M.2 NVMe drive with a USB 3.0 to M.2 adapter. - (Some CM4 carrier boards may offer direct M.2 slots). Use USB 3.0 Ports If using USB-connected storage, **always use the blue USB 3.0 ports** on the Raspberry Pi for maximum speed. ______________________________________________________________________ ### Recommendations for Execution Client SSD (2TB+) This device requires a large, fast drive. The recommendations are the same as for the single-device mode. #### USB Drive (EL) | | Brand/Model | Comment | Link | | --- | -------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | | **Samsung T7 2TB USB 3.2** | **Recommended for RPi4 users. Compatible with Raspberry Pi 4 and 5** | [More Info](https://tweakers.net/pricewatch/1560668/samsung-portable-ssd-t7-2tb-grijs/specificaties/) | Tip Some external disks consume more power than Raspberry Pi can deliver via USB. For Raspberry Pi 5, the max power output of the USB ports is 600mA if you're using a 3A supply, and 1600mA if you're using a 5A supply. You can edit `/boot/firmware/config.txt` and add `usb_max_current_enable=1` to disable the current limit. Please read the documentation: [Link](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html) #### NVMe Drive (EL) These drives need adapters (HAT or USB). See below. | | Brand/Model | Controller | Comment | Link | | --- | -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Lexar NM790 2TB m.2 2280** | Maxiotek MAP1602A | single side design 4TB available | [Product page](https://americas.lexar.com/product/lexar-nm790-m-2-2280-pcie-gen-4x4-nvme-ssd/) [More Info](https://www.techpowerup.com/ssd-specs/lexar-nm790-2-tb.d1494) | | | **Goodram PX700 2TB m.2 2280** | Maxiotek MAP1602A | single side design 4TB available | [Product page](https://www.goodram.com/en/products/goodram-px700-ssd-2/) | | | **Micron 2400 2TB m.2 2230** | Silicon Motion SM2269XT | single side design ~4 W (Max) small 2230 form factor low power consumption low heat | [Product page](https://www.micron.com/products/storage/ssd/client-ssd/2400-ssd) [More Info](https://www.techpowerup.com/ssd-specs/micron-2400-2-tb.d810) | | | **Samsung 980 Pro 2TB m.2 2280** | Samsung Elpis (S4LV003) | single side design 7.2 W (Max) | [Product page](https://www.samsung.com/pl/memory-storage/nvme-ssd/980-pro-2tb-nvme-pcie-gen-4-mz-v8p2t0bw/) [More Info](https://www.techpowerup.com/ssd-specs/samsung-980-pro-2-tb.d52) | Note Double-sided NVMe m.2 memory modules (with memory chips on both sides of the PCB) may not be fully compatible with every enclosure due to physical dimensions, specifically the height of the m.2 slot in the adapter/enclosure. #### NVMe Hat (Pi 5) (EL) | Brand | Link | | --------------------------- | --------------------------------------------------------------------------------------------------- | | Pimoroni | [NVMe Base for Raspberry Pi 5](https://shop.pimoroni.com/products/nvme-base?variant=41219587178579) | | Raspberry Pi m.2 Hat | | | Pineboards HatDrive: Bottom | | | Pineboards HatDrive: Top | | | Waveshare 26583 | | ### Recommendations for Consensus Client SSD (500GB+) This device requires a smaller, but still fast and reliable drive. #### USB Drive (CL) | | Brand/Model | Comment | Link | | --- | ---------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | | **Samsung T7 500GB USB 3.2** | **Recommended for RPi4 users. Compatible with Raspberry Pi 4 and 5** | [More Info](https://tweakers.net/pricewatch/1560668/samsung-portable-ssd-t7-2tb-grijs/specificaties/) | #### NVMe Drive (CL) These drives need adapters (HAT or USB). Choose a reputable brand. 500GB or more are suitable sizes. | | Brand/Model | Controller | Comment | Link | | --- | -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Lexar NM790 1TB m.2 2280** | Maxiotek MAP1602A | single side design 4TB available | [Product page](https://americas.lexar.com/product/lexar-nm790-m-2-2280-pcie-gen-4x4-nvme-ssd/) [More Info](https://www.techpowerup.com/ssd-specs/lexar-nm790-2-tb.d1494) | | | **Goodram PX700 1TB m.2 2280** | Maxiotek MAP1602A | single side design 4TB available | [Product page](https://www.goodram.com/en/products/goodram-px700-ssd-2/) | | | **Micron 2400 1TB m.2 2230** | Silicon Motion SM2269XT | single side design ~4 W (Max) small 2230 form factor low power consumption low heat | [Product page](https://www.micron.com/products/storage/ssd/client-ssd/2400-ssd) [More Info](https://www.techpowerup.com/ssd-specs/micron-2400-2-tb.d810) | | | **Samsung 980 Pro 1TB m.2 2280** | Samsung Elpis (S4LV003) | single side design 7.2 W (Max) | [Product page](https://www.samsung.com/pl/memory-storage/nvme-ssd/980-pro-2tb-nvme-pcie-gen-4-mz-v8p2t0bw/) [More Info](https://www.techpowerup.com/ssd-specs/samsung-980-pro-2-tb.d52) | #### NVMe Hat (Pi 5) (CL) Same HATs as recommended for the EL client can be used here with a smaller NVMe drive. See [NVMe Hat (Pi 5) (EL)](#nvme-hat-pi-5-el) section above. #### USB to NVMe adapters (CL) Same adapters as recommended for the EL client can be used here with a smaller NVMe drive. See [USB to NVMe adapters (EL)](#usb-to-nvme-adapters-el) section above. ______________________________________________________________________ ## SD Card Reader and Writer You only need **one** SD card reader/writer to flash the operating system onto both microSD cards. ## MicroSD Cards You will need **two** microSD cards, one for each Raspberry Pi. - Requirement: 32GB minimum capacity. Faster cards can improve boot times. - Recommendations: (Refer to the list in the [Single Mode Recommendations](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#microsd-card)) - purchase two cards. ## Power Supplies You will need **two** power supplies, one appropriate for each Raspberry Pi model you are using. - **Raspberry Pi 5:** Official Raspberry Pi 27W USB-C Power Supply (5.1V/5A) is strongly recommended. - **Raspberry Pi 4:** Official Raspberry Pi 15.3W USB-C Power Supply (5.1V/3A) is strongly recommended. - **CM4:** Depends on the carrier board requirements. Check the carrier board documentation. Using the official power supplies ensures stability, especially when powering connected peripherals like SSDs. ## Enclosures and Active Cooling **Active cooling is mandatory for both Raspberry Pi devices** in a dual-node setup to prevent thermal throttling and ensure stability. You will need **two** enclosures with active cooling. - **For Raspberry Pi 5:** Choose one of the recommended cases with integrated fan/heatsink. (Refer to [Single Mode Recommendations](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#enclosures-for-raspberry-pi-5)). - **For Raspberry Pi 4:** Choose one of the recommended cases with integrated fan/heatsink. (Refer to [Single Mode Recommendations](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#enclosures-for-raspberry-pi-4b)). - **For CM4:** Ensure your chosen carrier board has a suitable active cooling solution attached or available. ## Optional: LCD Display You can add an optional LCD display to **either or both** Raspberry Pi devices for at-a-glance monitoring. - Refer to the [LCD Monitoring Guide](https://docs.web3pi.io/monitoring/lcd/index.md) for hardware and setup details. ## Networking - You will need **two** Ethernet cables (Cat5e or better). - Ensure your router or network switch has at least two available Gigabit Ethernet ports. - Refer to the main [Prerequisites Guide](https://docs.web3pi.io/setup/prerequisites/index.md) for internet speed requirements. ______________________________________________________________________ Choosing the right hardware ensures a stable and performant dual-device node setup. Remember to clearly label your devices during assembly to avoid confusion! # Web3 Pi: Installation Monitoring Guide - Dual Device Node Once you have flashed the boot cards and assembled the hardware, you're ready to install and activate Web3 Pi in dual device mode. ## Pre-installation Checklist - Ensure your Raspberry Pis have active cooling. - The Execution Client should have at least 2 TB SSD storage. The Consensus Client needs at least 256 GB. - You should have flashed two boot cards. Make sure the boot card for the Execution Client is loaded into the machine with the larger SSD drive, and the Consensus Client boot card is inserted into the smaller one. - Make sure the devices are protected against power surges with a UPS - Connect the Raspberry Pis using Ethernet cables to your network, and ensure the network is connected to the Internet. ## Installation Installation will begin automatically as soon as you connect the power cable. You can monitor the installation on both devices by entering the corresponding addresses in your browser, based on the previously defined hostnames. The default values are: - - - The monitoring should start working approximately three minutes after the device is first switched on. Replace `eop-1-exec` and `eop-1-cons` with your hostnames that you entered during the microSD card burning process. After approximately 3 minutes from powering on the device for the first time, you should see a similar page - for both devices. Note Leave the device for about 8-15 minutes to complete the installation process. Do not disconnect power during this time. The time may vary depending on the bandwidth of the internet connection. ## Grafana Dashboard Access Next, click the link to the Grafana dashboard. If everything has gone smoothly, you should see the login panel. The default username is **'admin'**, and the password is **'admin'**. You will be required to change the password upon first login. In the Grafana Panel, click on the **dashboard** named **'Ethereum Nodes Monitor'**. Note Pay attention to the status of the consensus and execution clients. Initially, both will be 'inactive' In the next step, the execution client will change to 'waiting'. Then both will transition to the 'syncing' state. Grafana URL: [http://eop-1-exec.local:3000](http://eop-1.local:3000) ## Blockchain Synchronization At this point, the **blockchain synchronization process** will begin and will take approximately 19 hours. The CPU load will increase until it reaches its maximum possible value. Disk usage will grow to around 1.2TB. ## Synchronization Complete Full synchronization will be achieved when the status of both the execution and consensus clients turns green ("synced"). ## SSH Access After the installation completes successfully, you should have SSH access to the Web3 Pi node. Username: **ethereum**\ Password: **ethereum** You can use **[your-hostname].local** as the SSH address or the **IP address** if you know it. If the 'ethereum' user does not exist, it means the installation failed unexpectedly (in such case, please contact support). By default, the `ethereum` user is required to change the password during the first login. # Web3 Pi Image Installation Guide This guide will walk you through the process of writing the Web3 Pi image to a microSD card using the Web3 Pi Imager tool. ## Getting Started Follow the instructions below to write images on the microSD card: 1. Download and install [Web3 Pi Imager](https://github.com/Web3-Pi/web3-pi-imager/releases/latest) 1. Insert the microSD card into the card reader and connect the reader to your PC 1. Open the **Web3 Pi Imager** on your PC 1. Choose the **Single Mode Device** ## Configuration Options For Dual Mode device, the following settings can be configured. In this mode, we set separate hostnames, clients, and ports for the execution layer device and the consensus layer device: - **Image version:** Default is the latest version of Web3 Pi Image - **Default Ethereum Network:** Choice between `Mainnet`, `Sepolia`, or `Holesky` - **Execution device hostname:** Use a unique hostname for the execution layer device. Default is `eop-1-exec.local` - **Consensus device hostname:** Use a unique hostname for the consensus layer device. Default is `eop-1-cons.local` - **Execution client:** Choose between `Geth` or `Disabled` for the execution layer device - **Execution Port for Geth:** `30303` for the execution layer device - **Consensus Client:** Choose between `Nimbus` or `Lighthouse` for the consensus layer device - **Consensus Client Port:** `9000` for the consensus layer device - **Enable Grafana Monitoring:** Turn on the advanced monitoring system by Grafana - **Format storage:** Option to format external storage during installation ## Advanced Options If you click the **ADVANCED** button, you can configure these additional options. These advanced settings will be applied to both the execution layer device and the consensus layer device: - **Execution endpoint address:** Optional custom endpoint for execution client - **Locale settings:** Including: - Time zone selection - Keyboard layout - **Wireless LAN configuration:** Including: - SSID - Password - Wireless LAN country selection Note Wired Ethernet connection is recommended over Wi-Fi to ensure better synchronization. ## Drive Selection After setting up the configuration and clicking **NEXT**, a dialog box will appear allowing you to select the drive where the image with settings will be saved. - **Drive selection:** The list shows available storage devices - **Display options:** - By default, only drives smaller than 300GB are displayed - Checking the "Show large external storage device" option will display devices larger than 300GB Note Make sure you select the correct drive to avoid data loss on other devices ## Accepting Terms of Use After selecting your target drive, a warning dialog will appear informing you that all data on the selected device will be erased. - Confirms that all existing data on the selected drive will be permanently deleted - You must accept the terms to proceed (the "Yes" button remains disabled until accepted). The full Terms of Use can be found at [www.web3pi.io/terms](https://www.web3pi.io/terms). Note This is your final confirmation before the write process begins - ensure you have selected the correct device ## Writing Process - Execution Device After confirmation, the writing process for execution device begins. - **Writing process:** The progress bar displays the current writing status - **Verification phase:** After the writing completes, the verification process automatically starts. This step ensures data integrity and proper image installation. Note Do not disconnect or remove the storage device until both the writing and verification processes are complete ## Replacing cards At this point, you need to switch the SD cards. Remove the card that has been written for the execution layer device and insert a new card for the consensus layer device. Select the appropriate storage destination for the consensus device image and confirm by clicking "Yes" to proceed with the writing process. ## Writing Process - Consensus Device Now the process of writing the card for the consensus layer device will begin. - **Writing process:** The progress bar displays the current writing status - **Verification phase:** After the writing completes, the verification process automatically starts. This step ensures data integrity and proper image installation. Note Do not disconnect or remove the storage device until both the writing and verification processes are complete ## Final Steps Now that you have both cards prepared, you will see a message about the possibility of installing the prepared cards in the appropriate devices. At this stage, you can click **NEXT** and complete the process. In the following steps, you will be able to assemble both devices and install the prepared cards in the corresponding slots. # Web3 Pi: Hardware Assembly This assembly guide is primarily aimed at assembling the components included in the Welcome Box, but will also be useful for anyone assembling their own hardware. Info To avoid errors during the first setup, please follow the instructions precisely. Please also see the [video instructions](https://www.youtube.com/watch?v=-3Bj0rSCskk) for more information. If you have a Welcome Box, unpack the contents and check them against the components listed [here](https://docs.web3pi.io/welcome-box/index.md). ## Components Overview 1. Aluminium Top Cover with Screw Points 1. Aluminium Case 1. Cooling Fins and Exhaust Vent 1. Fan Port Access 1. POE HAT Connection 1. GPIO Access 1. MIPI Ports Access 1. 30mm PWM Blower-type Fan 1. UART Connector 1. RTC Battery Connector Access 1. PCIe Port Access 1. PCIE Film Strip 1. Power Button and LED Light 1. THRML M.2 Heatsink 1. M.2 NVMe Drive Socket Some parts are in two zipper bags. Open them and carefully pour out the contents. You will find: - Screws (two types) - Rubber feet - Two ribbon cables. You need one, the other one is a spare ## Assembly Instructions ### 1. Prepare the Raspberry Pi 5 Place the thermal pads on the CPU, RP1, RAM and PMIC Chip of the RPi 5. There are different versions of this case on the market: * If you have four thermal pads, place them in the areas marked in blue. * If you have two thermal pads in the set, place them on the CPU and PMIC (left corner, near the USB-C connector). ### 2. Connect the Fan Connect the NEO 5 fan to the RPi 5 fan connector as shown in the image. Please pay attention to how the cable is routed. Note There may be a small plug inserted in the fan connector. Remove it. ### 3. Connect PCIe Ribbon Cable Connect the PCIe flat ribbon cable to the Raspberry Pi 5 PCIe port. Be careful when handling brown PCIe flip/cover. Pull up the brown flip to release the lock. ### 4. Place Raspberry Pi in the Case Drop in the RPi 5 inside the **Argon NEO 5 M.2 NVMe Case** Warning After inserting and pressing the RPi 5 into the central part of the Argon Neo 5 case, they will adhere due to the stickiness of the thermal pads. To ensure good thermal conductivity, do this once and avoid removing the RPi 5 from this part of the case again. ### 5. Route the PCIe Cable The PCIe flat ribbon cable should be threaded through the hole in the case, as shown in the picture. ### 6. Connect PCIe Cable to M.2 Board Carefully connect the Raspberry Pi 5 with the PCIe flat ribbon cable **with copper facing up** to the **Argon NEO 5 M.2 NVMe Carrier Board Case.** Flip up the cover on the M.2 NVMe Expansion Board. ### 7. Insert MicroSD Card Here we want you to insert the PREVIOUSLY flashed microSD card with Web3 Pi image. ### 8. Prepare M.2 NVMe Drive Installation Connect your **M.2 NVMe Drive** to the **Argon NEO 5 M.2 NVMe Carrier Board.** Detailed instructions for this process are described in the following steps. ### 9. Check NVMe Compatibility Connect your **M.2 NVMe Drive** to the **Argon NEO 5 M.2 NVMe Carrier Board.** Detailed instructions for this process are described in the following steps. This Board will accept **M.2 Key M** and **M.2 Key B+M** NVMe Storage Drive. Warning This Board will accept **M.2 Key M** and **M.2 Key B+M** NVMe Storage Drive. ### 10. Remove Heatsink Cover Remove the "THRMK M.2 Heatsink" cover by unscrewing the four screws at its corners. ### 11. Adjust Screw Mount Position Move the screw point on the Board to the appropriate size of your Storage Drive. ### 12. Insert NVMe Drive Insert the NVMe drive into the M.2 slot as shown in the picture. ### 13. Secure the NVMe Drive Screw in the NVMe drive as shown in the picture. ### 14. Apply Thermal Pad Mount the thermal pad on the NVMe drive. There is no need to shorten it. Remember to remove the protective film from both sides. ### 15. Mount Metal Cover Mount the metal cover and screw it in using four screws with conical heads. ### 16. Secure Top Cover Secure the Aluminium Top Cover with 2 screws. ### LCD Display Option If you have a plastic cover with an LCD display, connect it according to the diagram instead of the original metal one. Warning Pay attention to the positioning of the cables when mounting the cover to ensure they don't mechanically obstruct the fan blades. ## Final Assembly The final result should look like this: Note Pay attention to the positioning of the cables when mounting the cover to ensure they don't mechanically obstruct the fan blades. ## Hardware Connections Once you have assembled your device, connect the Raspberry Pi as shown below: Refer to the following images to verify your setup. These show two typical configurations: - **With a USB drive:** - **With an NVMe drive:** Ensure all cables and storage devices are securely connected before proceeding. Note Before you connect power, make sure that the ethernet cable is connected with DHCP. Internet connection is required during the installation process. # Web3 Pi: Hardware Checklist **Active cooling** is required to avoid throttling and keep sufficient performance/stability of the system. As a **power supply**, we recommend using the official Raspberry Pi power supply for your model. Raspberry Pi + 2TB drive can use a significant amount of power so a sufficient power supply is important for stability. ## Single Device Node Requirements You can run a single device node on any of the following. - Raspberry Pi 5 - [see full details](#raspberry-pi-5) - Raspberry Pi 4 - [see full details](#raspberry-pi-4) - Raspberry Pi CM4/5 - [see ful details](#raspberry-pi-compute-module) Optionally, you can add an [LCD display](https://docs.web3pi.io/monitoring/lcd/index.md) for monitoring purposes. ### Raspberry Pi 5 - 1 x [Raspberry Pi 5 (8GB)](https://botland.store/raspberry-pi-5-modules-and-kits/23905-raspberry-pi-5-8gb-5056561803326.html) - 1 X [2TB SSD drive (external USB SSD or NVMe m.2 with adapter)](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#ssd-drive) - 1 X [SD Card reader/writer](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#sd-card-reader-and-writer) - 1 x [microSD Card](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#microsd-card) - 1 x [Power supply](https://botland.store/raspberry-pi-5-power-supply/23907-raspberry-pi-27w-usb-c-power-supply-official-51v-5a-psu-for-raspberry-pi-5-black-5056561803418.html) - 1 x [Raspberry Pi 5 Active Cooler](https://botland.store/raspberry-pi-5-mounting-elements/23925-raspberry-pi-active-cooler-heatsink-fan-for-raspberry-pi-5-5056561803357.html) ### Raspberry Pi 4 - 1 x [Raspberry Pi 4 (8GB)](https://botland.store/raspberry-pi-4b-modules-and-kits/16579-raspberry-pi-4-model-b-wifi-dualband-bluetooth-8gb-ram-18ghz-5056561800356.html) - 1 x [2TB SSD drive (external USB SSD or NVMe with m.2 to USB adapter](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#ssd-drive)) - 1 x [SD Card reader/writer](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#sd-card-reader-and-writer) - 1 x [microSD Card](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#microsd-card) - 1 X [Raspberry Pi 4 Active Cooler](https://botland.store/raspberry-pi-4b-cases/15106-case-justpi-for-raspberry-pi-4b-aluminum-with-dual-fan-black-lt-4b02-5903351242660.html) - 1 x [Power supply](https://botland.store/raspberry-pi-4b-power-supply/14348-power-supply-for-raspberry-pi-4-usb-c-51v-3a-original-black-644824914886.html) ### Raspberry Pi Compute Module The CM4/5 module needs a carrier board. There are many on the market. Minimum requiments are: - 1 x Raspberry Pi CM4/CM5 8GB - 1 x [2TB fast storage](https://docs.web3pi.io/setup/single-mode/hardware-recommendations/#ssd-drive) - 1 x Power supply - 1 x Raspberry Pi CM4 Active Cooler - 1 x 32GB+ storage for operating system (microSD or eMMC) - 1 x Motherboard Installing Web3 Pi on the CM4/5 requires more knowledge. CM4/5 modules come with built-in eMMC memory, and in this case, you need to use the **rpiboot** application before using the Raspberry Pi Imager. If your module does not have built-in memory and uses an SD card, the installation process is similar to a standard Raspberry Pi. More information can be found on the manufacturer's website: [Raspberry Pi Documentation](https://www.raspberrypi.com/documentation/computers/compute-module.html). In some cases, a bootloader update may be necessary, which is described here: [How to Update the Raspberry Pi Compute Module 4 Bootloader EEPROM](https://www.jeffgeerling.com/blog/2022/how-update-raspberry-pi-compute-module-4-bootloader-eeprom). # Web3 Pi: Recommended Hardware ## SSD Drive **2 TB** fast drive is required. **For the Raspberry Pi 5**, you have three options for storage: - external USB SSD drive (wide availability) - m.2 NVMe drive with NVMe HAT for Raspberry Pi 5 (max performance) - m.2 NVMe drive with USB m.2 adapter Raspberry Pi 5 has a PCIe x1 connector on board so with a special adapter m.2 NVMe drive can be used. This option gives the maximum possible performance. **For the Raspberry Pi 4**, you have two options for storage: - external USB SSD drive (wide availability) - SSD drive with USB adapter Note If you use USB always choose USB 3.0 ports (blue) Warning Do NOT use HDD drives! ### Recommended SSD Hardware #### USB Drive | | Brand/Model | Comment | Link | | --- | -------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | | **Samsung T7 2TB USB 3.2** | **Recommended for RPi4 users. Compatible with Raspberry Pi 4 and 5** | [More Info](https://tweakers.net/pricewatch/1560668/samsung-portable-ssd-t7-2tb-grijs/specificaties/) | Tip Some external disks consume more power than Raspberry Pi can deliver via USB. For Raspberry Pi 5, the max power output of the USB ports is 600mA if you're using a 3A supply, and 1600mA if you're using a 5A supply. You can edit `/boot/firmware/config.txt` and add `usb_max_current_enable=1` to disable the current limit. Please read the documentation: [Link](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html) #### NVMe Drive These drives need adapters. | | Brand/Model | Controller | Comment | Link | | --- | -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Lexar NM790 2TB m.2 2280** | Maxiotek MAP1602A | single side design 4TB available | [Product page](https://americas.lexar.com/product/lexar-nm790-m-2-2280-pcie-gen-4x4-nvme-ssd/) [More Info](https://www.techpowerup.com/ssd-specs/lexar-nm790-2-tb.d1494) | | | **Goodram PX700 2TB m.2 2280** | Maxiotek MAP1602A | single side design 4TB available | [Product page](https://www.goodram.com/en/products/goodram-px700-ssd-2/) | | | **Micron 2400 2TB m.2 2230** | Silicon Motion SM2269XT | single side design ~4 W (Max) small 2230 form factor low power consumption low heat | [Product page](https://www.micron.com/products/storage/ssd/client-ssd/2400-ssd) [More Info](https://www.techpowerup.com/ssd-specs/micron-2400-2-tb.d810) | | | **Samsung 980 Pro 2TB m.2 2280** | Samsung Elpis (S4LV003) | single side design 7.2 W (Max) | [Product page](https://www.samsung.com/pl/memory-storage/nvme-ssd/980-pro-2tb-nvme-pcie-gen-4-mz-v8p2t0bw/) [More Info](https://www.techpowerup.com/ssd-specs/samsung-980-pro-2-tb.d52) | Note Double-sided NVMe m.2 memory modules (with memory chips on both sides of the PCB) may not be fully compatible with every enclosure due to physical dimensions, specifically the height of the m.2 slot in the adapter/enclosure. #### NVMe Hat ##### NVMe HAT for Raspberry Pi 5 | Brand | Link | | --------------------------- | ---------------------------------------------------------------------------------------------------- | | Pimoroni | [Product page](https://shop.pimoroni.com/products/nvme-base?variant=41219587178579) | | Raspberry Pi m.2 Hat | [Product page](https://www.raspberrypi.com/products/m2-hat-plus/) | | Pineboards HatDrive: Bottom | [Product page](https://pineberrypi.com/products/hatdrive-bottom-2230-2242-2280-for-rpi5) | | Pineboards HatDrive: Top | [Product page](https://pineboards.io/products/hat-top-2230-2240-for-rpi5) | | Pineboards HatDrive: Nano | [Product page](https://pineboards.io/products/hatdrive-nano-nvme-2230-2242-gen-3-for-raspberry-pi-5) | | Waveshare 26583 | [Product page](https://www.waveshare.com/pcie-to-m.2-hat-plus.htm) | We do not recommend the following: - **KAmodRPi5 PCIe-M.2** - **Geekworm X1001** ## SD Card Reader and Writer You will use this on your PC for flashing the boot card. Since this operation takes time, we recommend a high-speed device. ## MicroSD Card Flashing a microSD card takes time, but it can be reduced by using a fast device. Additionally, using a fast micro SD card results in a shorter booting time. You will require at least 32GB capacity. A few examples: - [Silicon Power 3D NAND](https://www.tomshardware.com/best-picks/raspberry-pi-microsd-cards#section-best-microsd-card-overall) - [SanDisk Extreme Pro](https://www.tomshardware.com/best-picks/raspberry-pi-microsd-cards#section-great-speeds-best-for-pi-3) - [SanDisk Ultra](https://www.westerndigital.com/en-ap/products/memory-cards/sandisk-ultra-uhs-i-microsd-120-mbps?sku=SDSQUA4-064G-GN6MA) - [SanDisk Max Endurance](https://www.westerndigital.com/en-ap/products/memory-cards/sandisk-max-endurance-uhs-i-microsd?sku=SDSQQVR-064G-GN6IA) - [Kingston Canvas React](https://www.tomshardware.com/best-picks/raspberry-pi-microsd-cards#section-fastest-booting-raspberry-pi-microsd) - [Samsung 64 Evo Plus](https://www.samsung.com/pl/memory-storage/memory-card/evo-plus-128gb-microsd-card-2021-mb-mc128ka-eu/) - [Lexar Professional 1000X](https://www.amazon.com/Lexar-Professional-1000x-UHS-II-LSD64GCRBNA1000/dp/B00PLENZX4) [**More Information**](https://www.tomshardware.com/best-picks/raspberry-pi-microsd-cards) ## Enclosures ### Enclosures for Raspberry Pi 5 | | Brand/Model | Comment | Link | | --- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Argon NEO 5 M.2 NVMe** | +good cooling +metal -inconvenient access to the microSD card -m.2 slot not compatible with double side NVMe (easy modification possible with utility knife) | [Product page](https://argon40.com/products/argon-neo-5-m-2-nvme-for-raspberry-pi-5?_pos=1&_psq=Argon+NEO+5+M.2+NVME+PCIE+Case+for+Raspberry+Pi+5&_ss=e&_v=1.0) [Shop](https://botland.store/raspberry-pi-5-cases/24397-argon-neo-5-m2-nvme-pcie-case-for-raspberry-pi-5-with-fan-and-heatsink-aluminum-black-860011360049.html) | | | **Argon NEO 5** | +easy acces to microSD card +good cooling +metal | [Product page](https://argon40.com/products/argon-neo-case-for-raspberry-pi-5) [Shop](https://botland.store/raspberry-pi-5-cases/24095-argon-neo-5-bred-case-for-raspberry-pi-5-with-fan-black-and-red-6974297861856.html) | | | **Argon ONE V3 M.2 NVMe** | +good cooling +metal -m.2 slot not compatible with double side NVMe (easy modification possible with utility knife) | [Product page](https://argon40.com/products/argon-one-v3-m-2-nvme-case?_pos=1&_sid=44da22b52&_ss=r) [Shop](https://botland.store/raspberry-pi-5-cases/24396-argon-one-v3-m2-nvme-pcie-case-for-raspberry-pi-5-with-fan-and-heatsink-aluminum-black-860011360032.html) | | | **Argon ONE V3** | +good cooling +metal | [Product page](https://argon40.com/products/argon-one-v3-case-for-raspberry-pi-5?_pos=1&_psq=Argon+ONE+V3+Case+for+Raspberry+Pi+5&_ss=e&_v=1.0) [Shop](https://botland.store/raspberry-pi-5-cases/24395-argon-one-v3-case-for-raspberry-pi-5-with-fan-and-heatsink-aluminum-black-860011360025.html) | ### Enclosures for Raspberry Pi 4B | | Brand/Model | Comment | Link | | --- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Case justPi** | [assembly instructions](https://www.youtube.com/watch?v=qEsSK9WIRM4) | [Product page](https://botland.store/raspberry-pi-4b-cases/15106-case-justpi-for-raspberry-pi-4b-aluminum-with-dual-fan-black-lt-4b02-5903351242660.html) [Shop](https://botland.store/raspberry-pi-4b-cases/15106-case-justpi-for-raspberry-pi-4b-aluminum-with-dual-fan-black-lt-4b02-5903351242660.html) | | | **Argon One V2** | Fan control needs additional configuration as described by the manufacturer [manual](https://cdn.shopify.com/s/files/1/0556/1660/2177/files/AR1_PI4-V2_INSTRUCTION_MANUAL_20200922.pdf?v=1646125923) | [Product page](https://argon40.com/products/argon-one-v2-case-for-raspberry-pi-4) [Shop](https://botland.store/raspberry-pi-4b-cases/15391-raspberry-pi-4-aluminum-case-with-fan-argon-one-v2-grey-5904422301347.html) | | | **Argon One V2 m.2** | Fan control needs additional configuration as described by the manufacturer [manual](https://cdn.shopify.com/s/files/1/0556/1660/2177/files/AR1_NVME_INSTRUCTION_MANUAL_20220531.pdf?v=1659581194) | [Product page](https://argon40.com/products/argon-one-m-2-case-for-raspberry-pi-4) [Shop](https://botland.store/raspberry-pi-4b-cases/17273-raspberry-pi-4-aluminum-case-with-fan-argon-one-m2-grey-5904422328597.html) | # Web3 Pi: Installation Monitoring Guide - Single Device Node Now that the device is assembled and the card is inside, go back to the Web3 Pi Imager and follow the instructions: 1. Connect the necessary cables. 1. Ensure Internet connection (via DHCP) is available. 1. Turn on the device and then press the **NEXT** button. ## SD Card Installation Complete - Web3 Pi installer has been successfully written to the SD card. - At this point, the card is ready, and the installation process on the device begins. - Now the device is being searched on the network - this may take about 2 minutes, after which the user will be able to monitor the further installation process. ## Track Installation Progress Now you can click the "Track" button - a page with the software installation process on the device will open. Note From this point, the user can log in via SSH using the credentials **ethereum:ethereum** ## Monitor Installation You can monitor the installation process through a dedicated website: The monitoring should start working approximately three minutes after the device is first switched on. Replace `eop-1` with your hostname that you entered during the microSD card burning process in Web3 Pi Imager, if you used a name other than `eop-1`. After approximately 3 minutes from powering on the device for the first time, you should see a similar page. Note Leave the device for about 8-15 minutes to complete the installation process. Do not disconnect power during this time. The time may vary depending on the bandwidth of the internet connection. ## Installation Web Interface The Raspberry Pi with the Web3 Pi image on port 80 hosts an HTTP server that continuously displays the following in the web browser: - The installation stage - The hostname and IP address of the device - The full installation log and uptime - A link to the Grafana dashboard and a JSON status file The installation is divided into stages. The installation is complete when you see: "STAGE 100: Installation completed." This status is shown in the following screenshot. ## Grafana Dashboard Access Next, click the link to the Grafana dashboard. If everything has gone smoothly, you should see the login panel. The default username is **'admin'**, and the password is **'admin'**. You will be required to change the password upon first login. In the Grafana Panel, click on the **dashboard** named **'Ethereum Nodes Monitor'**. Note Pay attention to the status of the consensus and execution clients. Initially, both will be 'inactive' In the next step, the execution client will change to 'waiting'. Then both will transition to the 'syncing' state. Grafana URL: ## Blockchain Synchronization At this point, the **blockchain synchronization process** will begin and will take approximately 19 hours. The CPU load will increase until it reaches its maximum possible value. Disk usage will grow to around 1.2TB. ## Synchronization Complete Full synchronization will be achieved when the status of both the execution and consensus clients turns green ("synced"). ## SSH Access After the installation completes successfully, you should have SSH access to the Web3 Pi node. Username: **ethereum**\ Password: **ethereum** You can use **[your-hostname].local** as the SSH address or the **IP address** if you know it. If the 'ethereum' user does not exist, it means the installation failed unexpectedly (in such case, please contact support). By default, the `ethereum` user is required to change the password during the first login. ## Network Configuration Verification To check that the network is working correctly, SSH into the Rasberry Pi and run a `ping` command: ``` ping -c 4 google.com ``` You should see similar response: ``` PING google.com (142.250.186.206) 56(84) bytes of data. 64 bytes from waw07s05-in-f14.1e100.net (142.250.186.206): icmp_seq=1 ttl=59 time=2.83 ms 64 bytes from waw07s05-in-f14.1e100.net (142.250.186.206): icmp_seq=2 ttl=59 time=3.62 ms 64 bytes from waw07s05-in-f14.1e100.net (142.250.186.206): icmp_seq=3 ttl=59 time=2.23 ms 64 bytes from waw07s05-in-f14.1e100.net (142.250.186.206): icmp_seq=4 ttl=59 time=3.73 ms --- google.com ping statistics --- 4 packets transmitted, 4 received, 0% packet loss, time 3005ms rtt min/avg/max/mdev = 2.229/3.102/3.734/0.614 ms ``` You now have a fully operational Ethereum node running Geth and Nimbus. For more information on managing, configuring and troubleshooting your node, please refer to the [Managing Your Node](https://docs.web3pi.io/management/ssh/index.md) menu. # Web3 Pi Image Installation Guide This guide will walk you through the process of writing the Web3 Pi image to a microSD card using the Web3 Pi Imager tool. ## Getting Started Follow the instructions below to write images on the microSD card: 1. Download and install [Web3 Pi Imager](https://github.com/Web3-Pi/web3-pi-imager/releases/latest) 1. Insert the microSD card into the card reader and connect the reader to your PC 1. Open the **Web3 Pi Imager** on your PC 1. Choose the **Single Mode Device** ## Configuration Options For Single Mode device, the following settings can be configured: - **Image version:** Default is the latest version of Web3 Pi Image - **Default Ethereum Network:** Choice between `Mainnet`, `Sepolia`, or `Holesky` - **Hostname for Raspberry Pi:** Use a unique hostname. Default is `eop-1.local` - **Execution client:** Choose between `Geth` or `Disabled` - **Execution Port for Geth:** `30303` - **Consensus Client:** Choose between `Nimbus` or `Lighthouse` - **Consensus Client Port:** `9000` - **Enable Grafana Monitoring:** Turn on the advanced monitoring system by Grafana - **Format storage:** Option to format external storage during installation ## Advanced Options If you click the **ADVANCED** button, you can configure these additional options: - **Execution endpoint address:** Optional custom endpoint for execution client - **Locale settings:** Including: - Time zone selection - Keyboard layout - **Wireless LAN configuration:** Including: - SSID - Password - Wireless LAN country selection Note Wired Ethernet connection is recommended over Wi-Fi to ensure better synchronization. ## Drive Selection After setting up the configuration and clicking **NEXT**, a dialog box will appear allowing you to select the drive where the image with settings will be saved. - **Drive selection:** The list shows available storage devices - **Display options:** - By default, only drives smaller than 300GB are displayed - Checking the "Show large external storage device" option will display devices larger than 300GB Note Make sure you select the correct drive to avoid data loss on other devices ## Accepting Terms of Use After selecting your target drive, a warning dialog will appear informing you that all data on the selected device will be erased. - Confirms that all existing data on the selected drive will be permanently deleted - You must accept the terms to proceed (the "Yes" button remains disabled until accepted). The full Terms of Use can be found at [www.web3pi.io/terms](https://www.web3pi.io/terms). Note This is your final confirmation before the write process begins - ensure you have selected the correct device ## Writing Process After confirmation, the writing process to the selected storage device begins. - **Writing process:** The progress bar displays the current writing status - **Verification phase:** After the writing completes, the verification process automatically starts. This step ensures data integrity and proper image installation. Note Do not disconnect or remove the storage device until both the writing and verification processes are complete ## Final Steps Now after the card has finished writing you will see a screen informing you about installing the prepared card to the device. Keep Web3 Pi Imager open at this step and now we will start assembling the device. We will come back to this step after we finish assembling. # Advanced Setup This section provides advanced setup guides for your Web3 Pi node that aim to optimize your node's performance and reliability. None of these steps are required, but they can help you achieve better uptime and reduce maintenance burden. ## Table of Contents - [Two-Factor Authentication (2FA)](https://docs.web3pi.io/advanced-setup/2fa/index.md) - Add an extra layer of security to your Cockpit login. - [Backup Power](https://docs.web3pi.io/advanced-setup/ups/index.md) - Consider adding a backup power source to your node, in case of power outages. - [Power over Ethernet](https://docs.web3pi.io/advanced-setup/poe/index.md) - Use PoE (Power over Ethernet) instead of the included power supply. - [Firewall Configuration (UFW)](https://docs.web3pi.io/advanced-setup/ufw/index.md) - Configure UFW to control incoming and outgoing network traffic. - [The config.txt File](https://docs.web3pi.io/advanced-setup/config/index.md) - Learn how to configure boot options, hardware interfaces, and more. - [Overclocking](https://docs.web3pi.io/advanced-setup/OC/index.md) - Learn how to overclock your Raspberry Pi to improve performance. # Two-Factor Authentication (2FA) for Cockpit Adding Two-Factor Authentication (2FA) to Cockpit increases the security of your server by requiring a time-based one-time password (TOTP) in addition to your regular credentials. The Web3 Pi team developed a plugin to easily enable 2FA in Cockpit using a graphical interface. Alternatively, you can manually configure 2FA using the `libpam-google-authenticator` package. ## Step 1: Install Required Packages Navigate to the `Web3 Pi Updater` section in Cockpit and install `Two Factor Authentication Plugin for Cockpit`: Alternatively, you can install the plugin manually by opening a terminal and running the following command: ``` sudo apt-get install w3p-two-factor-auth ``` Note Cockpit will restart after the installation of the plugin, so you may need to refresh the page and log in again. ## Step 2: Configure 2FA After installing the plugin, navigate to the `Web3 Pi 2FA` section in Cockpit: Click `Enable Two-Factor Authentication` to start the setup process. Follow the on-screen instructions to set up 2FA: 1. Scan the QR code with your preferred authenticator app (e.g., Google Authenticator, Authy). 1. Enter the verification code from your authenticator app to complete the setup. 1. Save the emergency scratch codes in a safe place. Note Scratch codes are one-time use only. If you lose access to your authenticator app, enter one of these codes to log in and recreate your 2FA setup. ## Step 3: Test Your Setup 1. Log out of Cockpit. 1. Log back in. You should be prompted for a verification code from your authenticator app. ## Uninstalling 2FA To remove 2FA from Cockpit, navigate back to the `Web3 Pi 2FA` section and click `Disable Two-Factor Authentication`. ## Step 1: Install Required Packages Open a terminal and run: ``` sudo apt-get install libpam-google-authenticator -y ``` This installs the PAM module for Google Authenticator. ## Step 2: Configure Google Authenticator for Your User Run the following command to set up Google Authenticator with recommended options: ``` google-authenticator -t -d -f -r 3 -R 30 -W -Q UTF8 ``` Note - `-t` use TOTP instead of HOTP (recommended). - `-d` disable reuse of previously used TOTP tokens. - `-f` disable confirmation before writing the `~/.google_authenticator` file. - `-r 3 -R 30` limits the number of login attempts to 3 every 30 seconds. - `-W` by default google-authenticator allows the use of codes that were generated a little before or a little after the current time. This option disables that feature (recommended for security). - `-Q UTF8` specifies the encoding for the QR code. Change to `-Q ANSI` if you're having issues with viewing the QR code. - This will generate a secret key, QR code, and emergency scratch codes. - Scan the QR code with your preferred authenticator app (e.g., Google Authenticator, Authy). - Enter the verification code from your authenticator app to complete the setup. - Save the emergency scratch codes in a safe place. Note Scratch codes are one-time use only. If you lose access to your authenticator app, enter one of these codes to log in and recreate your 2FA setup. ## Step 3: Enable 2FA for Cockpit Use the following command to add the Google Authenticator PAM module to the Cockpit PAM configuration: ``` sudo bash -c 'echo "auth required pam_google_authenticator.so nullok" >> /etc/pam.d/cockpit' ``` This tells Cockpit to require a TOTP code during login. Note - The `nullok` option disables 2FA for users that do not have a `~/.google_authenticator` file. ## Step 4: Restart Cockpit Restart the Cockpit service to apply the changes: ``` sudo systemctl restart cockpit ``` ## Step 5: Test Your Setup 1. Log out of Cockpit. 1. Log back in. You should be prompted for a verification code from your authenticator app. ## Uninstalling 2FA To remove 2FA from Cockpit, simply delete the line you added to the PAM configuration: ``` sudo bash -c 'sed -i "/pam_google_authenticator.so nullok/d" /etc/pam.d/cockpit' ``` Then restart the Cockpit service: ``` sudo systemctl restart cockpit ``` You can also remove the generated `~/.google_authenticator` file and the installed packages if you no longer need 2FA: ``` sudo apt remove libpam-google-authenticator -y rm ~/.google_authenticator ``` # Overclocking ## Raspberry Pi 5 There are two things that can be tweaked on the Raspberry Pi 5 to increase Ethereum Node performance. - CPU frequency - PCIe generation Note about PCIe generation settings This makes sense only if using a PCIe to m.2 adapter for storage. ### CPU Overclocking By default, the Raspberry Pi 5 CPU clock is set to 2.4 GHz, but it is relatively easy to overclock. An overclocked CPU with a significant load will require an active cooling solution or a high-quality cooling case. The maximum stable clock that can be achieved depends on a particular device. Safe for all devices is 2.6 GHz. The reasonable top is 3.0 GHz. The Raspberry Pi has enough power to handle an Ethereum node without OC, so our recommendation is to keep stable settings like 2.6 GHz. #### How to overclock the CPU - Edit the */boot/firmware/config.txt* file: ``` sudo nano /boot/firmware/config.txt ``` - Find the last `[pi5]` section, almost at the end of the file. Look for this comment: ``` [rpi5] # Overclocking for Raspberry Pi 5 # Active cooling is required over_voltage_delta=50000 arm_freq=2800 #2400MHz is default #3000MHz is max (not all boards will work stable) #2800MHz is reasonable OC ``` - Exit the editor by pressing `Ctrl+x` and save the changes. - Restart the device: ``` sudo reboot ``` - After reboot, you can check if the frequency is correctly recognized by the OS. ``` sudo cat /sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_max_freq ``` It should output `2600000` If the procedure is successful, the device should be up and running with the updated OC settings. For more information about overclocking the Raspberry Pi 5, please visit: ### PCIe generation select The Raspberry Pi by default uses PCIe gen 2. But the Broadcom BCM2712 offers PCIe generation 3, which is twice as fast. By default, it is set to gen 2 because of compatibility reasons with different adapters. In most cases, you can safely set it to gen 3, which can double the performance of the NVMe drive. - Edit the */boot/firmware/config.txt* file: ``` sudo nano /boot/firmware/config.txt ``` - Find the last `[pi5]` section, almost at the end of the file. Look for this comment: ``` #Enable PCIe dtparam=pciex1 #Enable PCIe gen.3 (default is gen.2) dtparam=pciex1_gen=3 ``` - Exit the editor by pressing `Ctrl+x` and save the changes. - Restart the device: ``` sudo reboot ``` For more information, please visit: ## Raspberry Pi 4 To overclock the Raspberry Pi 4, you need to edit the config.txt file located in the /boot/firmware/ directory. 1. **Access the File:** 1. Open a terminal on your Raspberry Pi. 1. Edit the `config.txt` file using a text editor such as `nano`. ``` sudo nano /boot/firmware/config.txt ``` 1. **Add Overclocking Settings:** 1. Uncomment the following lines near the end of the `config.txt` file. Adjust the values based on your desired overclock settings and the stability of your system. ``` [pi4] over_voltage=6 arm_freq=1800 gpu_freq=600 ``` **Explanation:** - `over_voltage=6`: Increases the core voltage. Values range from 0 to 8. Higher values increase stability but also generate more heat. - `arm_freq=1800`: Sets the CPU frequency to 1800 MHz (1.8 GHz). - The default is 1500 MHz - Moderate OC is 1800 MHz - A high overclock is 2000 MHz - `gpu_freq=600`: Sets the GPU frequency to 600 MHz. - The default is 500 MHz - Moderate OC is 600 MHz - A high overclock is 750 MHz - **Save and Reboot:** - Save the file (`Ctrl+O` and `Enter` in nano) and exit the text editor (`Ctrl+X` in nano). - Reboot the Raspberry Pi to apply the changes. ``` sudo reboot ``` ## Raspberry Pi CM4 Overclocking the Raspberry Pi Compute Module 4 (CM4) is similar to overclocking the Raspberry Pi 4, but there are a few key differences to consider due to the form factor and intended use cases of the CM4. ### Similarities 1. **Configuration File:** 1. Both use the `config.txt` file located in the `/boot` directory for overclocking settings. 1. **Overclocking Parameters:** 1. Parameters such as `over_voltage`, `arm_freq`, and `gpu_freq` are used in the same way to adjust voltage, CPU frequency, and GPU frequency. 1. **Monitoring and Testing:** 1. Tools and methods for monitoring temperature, checking for throttling, and stress testing are the same. ### Differences 1. **Form Factor and Cooling:** 1. The CM4 is designed to be used with custom carrier boards, which may affect cooling solutions. Ensure your carrier board design allows for adequate cooling, especially when overclocking. 1. **Power Supply:** 1. The power supply and power delivery to the CM4 might be different depending on the carrier board. Ensure that the carrier board can supply sufficient power for overclocking. ## Monitoring and Stability 1. **Monitor Temperatures** 1. Use tools like `vcgencmd` to monitor the temperature of your Raspberry Pi. ``` vcgencmd measure_temp ``` - Ideally, temperatures should remain below 85°C. If temperatures are higher, consider improving your cooling solution. - **Stress Test** - Run stress tests to ensure stability. The `stress` tool can be used for this purpose. ``` sudo apt install stress stress --cpu 4 --timeout 600 ``` 1. **Check for Throttling** 1. Use `vcgencmd` to check if the Raspberry Pi is throttling due to high temperatures or insufficient power. ``` vcgencmd get_throttled ``` - A result of `0x0` indicates no throttling. ## Safety Tips 1. **Incremental Changes:** Start with small increments and gradually increase the values. Monitor stability and temperatures at each step. 1. **Cooling:** Ensure you have sufficient cooling. Consider adding a fan or better heatsinks if necessary. 1. **Power Supply:** Use a high-quality power supply that can handle the increased power demands. 1. **Testing:** Perform extensive testing to ensure that your system remains stable under load. ## Conclusion Overclocking the Raspberry Pi can provide significant performance improvements, making it more capable for an Ethereum node. However, it is crucial to approach overclocking with caution, ensuring adequate cooling and power supply, and thoroughly testing for stability. By following these guidelines, you can safely and effectively overclock your Raspberry Pi to meet your performance needs. # Advanced Setup: The config.txt File ## Overview Web3 Pi utilizes a central configuration file, `/boot/firmware/config.txt`, to manage both its own settings (like which clients to run and network selection) and the underlying Raspberry Pi hardware configuration (like boot options, hardware interfaces, and overclocking). This file is read by the Raspberry Pi firmware **during the early boot process**. **For most users, the default settings generated by the Web3 Pi Imager are sufficient and should not need modification.** This page is intended for advanced users who understand the implications of changing these parameters. **⚠️ WARNING:** Incorrectly editing `/boot/firmware/config.txt` can prevent your Raspberry Pi from booting correctly or cause your Ethereum node clients to malfunction. **Always back up the file before making changes.** ## Location and Editing The configuration file is located at: `/boot/firmware/config.txt` You will need root privileges to edit this file. Connect via [SSH](https://docs.web3pi.io/management/ssh/index.md) and use a text editor like `nano`: ``` # First, create a backup sudo cp /boot/firmware/config.txt /boot/firmware/config.txt.backup # Then, edit the file sudo nano /boot/firmware/config.txt ``` After saving changes, you must reboot your Raspberry Pi for them to take effect: ``` sudo reboot ``` ## Web3 Pi Specific Sections These sections control the behavior of the Web3 Pi software suite. ### [web3pi] Section - `geth=true|false`: Enables or disables the Geth execution client service (w3p_geth). - `nimbus=true|false`: Enables or disables the Nimbus consensus client service (w3p_nimbus-beacon). - `lighthouse=true|false`: Enables or disables the Lighthouse consensus client service (w3p_lighthouse-beacon). (Note: Typically, only one consensus client should be enabled). - `influxdb=true|false`: Enables or disables the InfluxDB time-series database service (for monitoring). - `grafana=true|false`: Enables or disables the Grafana dashboard service (for monitoring). - `bsm=true|false`: Enables or disables the Basic System Monitor service. - `bnm=true|false`: Enables or disables the Basic Eth2 Node Monitor service. - `exec_url=http://localhost:8551`: Specifies the URL the consensus client uses to connect to the execution client's Engine API. The default assumes both clients are on the same machine. - `eth_network=mainnet|sepolia|hoodi|...`: Crucially, sets the target Ethereum network for all clients. Must match the network you intend to sync. ### Client Port Sections ([geth], [nimbus], [lighthouse]): - `geth_port=30303`: Sets the P2P port Geth uses for peer discovery and communication. - `nimbus_port=9000`: Sets the P2P port Nimbus uses. - `lighthouse_port=9000`: Sets the P2P port Lighthouse uses. Make sure to update the [UFW Firewall](https://docs.web3pi.io/advanced-setup/ufw/index.md) after changing these ports. ## Standard Raspberry Pi Sections The rest of the config.txt file contains standard Raspberry Pi configuration directives, grouped under conditional filters like [all], [pi4], [pi5], [cm4], etc. These control hardware aspects: - Boot Options: (`kernel`, `cmdline`, `initramfs`) Defines how the Linux kernel is loaded. - Hardware Interfaces: (`dtparam=audio`, `i2c_arm`, `spi`, `enable_uart`) Enables or disables onboard hardware like audio, I2C, SPI, and serial ports. - Display Settings: (`disable_overscan`, `hdmi_drive`, `hdmi_force_hotplug`, `display_auto_detect`) Configures HDMI output behavior. - Graphics: (`dtoverlay=vc4-kms-v3d`) Configures the graphics driver. - Camera: (`camera_auto_detect`) Auto-detects connected cameras. - USB: (`dtoverlay=dwc2`, `usb_max_current_enable`) Configures USB ports, including enabling higher current output on Pi 5. - PCIe (Pi 5 / CM4): (`dtparam=pciex1`, `dtparam=pciex1_gen=3`) Important for NVMe drives. Enables the PCIe interface and sets its speed (Gen 2 or Gen 3). Web3 Pi typically enables Gen 3 for better NVMe performance. - Overclocking: (Lines often starting with # over_voltage, # arm_freq) These settings (commented out by default) allow advanced users to potentially increase CPU performance. Requires active cooling and carries risks of instability or hardware damage if done improperly. ## Further Reading For an exhaustive explanation of all standard Raspberry Pi config.txt options, refer to the official documentation: - [Official Raspberry Pi config.txt Documentation](https://www.raspberrypi.com/documentation/computers/config_txt.html) Remember to exercise caution when editing this file. Stick to the defaults unless you have a specific need and understand the parameter you are changing. # Internet Failover (LTE) Internet Failover is a built-in feature of **Web3 Pi vOS** — it ships in every vOS image, disabled by default; no extra software to install. Your Ethereum node normally runs on Ethernet. With Internet Failover enabled, you plug a USB LTE modem (with a SIM card, PIN disabled) into the Raspberry Pi and the node survives internet outages on its own: - **If the Ethernet cable dies** (unplugged, switch failure), the system moves to LTE **within seconds**. - **If the cable looks fine but the internet behind it is dead** (ISP outage — the most common case), a watchdog notices within ~20 seconds and forces traffic onto LTE. - On every switch, the node's stale connections are closed immediately so Geth and Nimbus start reconnecting over the new path right away. **All peer connections are dropped in the process** and the clients rebuild them from scratch, which takes a few minutes — the node may briefly stumble on sync or attestations during that window, but on a good LTE link (≥ 20/10 Mbit/s) it recovers full operation **on its own** within a few to a dozen or so minutes, with no intervention. - While on LTE the system enters **data-saving mode**: upload is shaped, automatic system updates are paused, and every megabyte is metered and visible in the control panel. - When Ethernet is healthy again for 2 minutes straight, traffic moves back automatically and data-saving mode ends. No human action at any point. - A WiFi network can optionally sit between Ethernet and LTE as a middle fallback (priority: **Ethernet → WiFi → LTE**). The validator is never restarted No failover code path ever touches the validator process. In the worst case the watchdog may restart the *beacon* service — at most once per outage, as a last resort — but the validator service is never restarted by failover. Ever. You provide the modem and the SIM; one action in `control-panel.sh` turns the feature on. ______________________________________________________________________ ## Requirements at a glance | Requirement | Value | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Modem class | USB LTE modem that presents itself as a **USB network card** (`cdc_ether`) with its own onboard dial/NAT/DHCP — see the recommended list below | | USB port | **USB 3.0** port on the Pi (stability and power, not speed — see below) | | SIM | **Full LTE** (not LTE-M / NB-IoT), data plan sized for node traffic, **PIN disabled** | | Link quality | At least **20 Mbit/s down / 10 Mbit/s up** through the modem — measure with the built-in speed test (control panel → `F` → `8`) | | Subnets | Every failover link must use a **different IP subnet** (modem LAN vs your home LAN vs WiFi) | If the LTE link at your location cannot deliver the 20/10 minimum, no failover algorithm can keep an Ethereum node synced on it — the node will lag on LTE and catch up when the faster link returns. Measure first, then decide. ______________________________________________________________________ ## Choosing a modem The failover treats the modem as a dumb USB network card: it must enumerate as a `cdc_ether` (or `rndis_host`) device with its own onboard dial, NAT and DHCP. Anything that needs ModemManager, QMI, MBIM or PPP dialing on the host **does not qualify**. ### Recommended models | # | | Model | Price (PL, 2026) | Notes | | --- | --- | --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | | **ZTE MF833N** | ~109–126 PLN | Bench-tested end-to-end on the shipped image. In production, widely stocked. No external antenna ports. | | 2 | | **ZTE MF79N** | ~149 PLN | Still in production. **2× TS-9 external antenna ports** under the flip-open side caps (most retail listings omit them) — the pick for weaker-signal sites. Occasional mode-switch retries on some units (the system retries automatically). | | 3 | | **ZTE MF833U1** | ~109–139 PLN | Sibling variant of the MF833N — same class, no antenna ports. | | 4 | | **Huawei E8372h-320** | ~140–160 PLN | Works well (`192.168.8.x` subnet avoids common LAN collisions), but EOL — buy only genuine stock and check `lsusb` on arrival (see the avoid list). | All ZTE models above use the `192.168.0.0/24` subnet on their LAN side by default — read the *distinct subnets* requirement below. ### Avoid list | Model | Why | | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Huawei E3372-325"** (current retail — actually a **Brovi** device, USB ID `3566:2001`) | Broken mode-switch on Linux. This is the #1 trap: cheap, sold everywhere, looks like the classic Huawei. **Do not buy.** If `lsusb` shows `3566:*`, return it. | | Alcatel/TCL IK41VE1 | Firmware lottery (MBIM vs RNDIS) — you cannot know what you are buying. | | D-Link DWM-222 (rev A2) | Exposes serial/QMI only — fails the plug-and-play requirement. | | Netgear Nighthawk / ZTE 5G pucks | Battery-powered hotspots: the battery is a wear item that swells on 24/7 power; far more expensive than the class needs. | | Sierra Wireless EM/MC modules | MBIM/QMI only, no onboard router mode. | ### Quick identification (`lsusb`) | ID seen | Meaning | Verdict | | ---------------------------------- | ------------------------------------------ | ------------ | | `19d2:1225` → `19d2:1405` | ZTE MF79N, MF833N (storage → network mode) | ✅ | | `12d1:1f01` → `12d1:14dc` / `14db` | Huawei HiLink (E3372h / E8372h) | ✅ | | `12d1:*` → `12d1:1506` / `1442` | Huawei **Stick/NCM firmware** | ❌ | | `3566:2001` | **Brovi** fake-Huawei | ❌ return it | | `2001:ac01` → `2001:7e3d` | D-Link DWM-222 A2 | ❌ | ### USB port and placement Use a **USB 3.0** port. This is about connection stability and power delivery, not throughput (these modems are USB 2.0 devices electrically): on USB 2.0 ports we observed modems periodically resetting, failing to hold speed, or not enumerating at all (`can't set config, error -110`) — all of them ran stably on USB 3.0. On the Pi 5 the USB 3.0 ports sit next to the Ethernet jack, so a wide modem body can press against the network plug. It fits, but a **short USB extension cable** removes the squeeze entirely and also guarantees firm seating. One more bench finding: **horizontal orientation beats vertical** for signal — conveniently, that is the natural position of a stick in the Pi's side ports. ______________________________________________________________________ ## SIM card requirements - **Full LTE**, not LTE-M / NB-IoT (an Ethereum node needs real bandwidth). 5G is unnecessary — a failover link cannot use the extra speed. - **Disable the SIM PIN before inserting it** (in a phone, or once via the modem's web UI). This is the #1 real-world failure: a PIN-locked SIM enumerates fine, hands out a DHCP address, and moves **zero** data. - **Pick a different carrier than your home ISP** — otherwise one regional outage can take down both links at once. - **Plan size — bench-measured (Hoodi testnet, node parked on LTE)**: - node **without a validator**: ≈ **0.7 GB/hour ≈ 17 GB/day** (short-window measurement on a constrained uplink — treat it as the floor); - node **with one active validator**: ≈ **2.9 GB/hour ≈ 69 GB/day**, steady across a full 24 h dwell — and roughly **half of that is upload**: once the uplink is not the bottleneck, the beacon *serves* data to its ~20 peers. Budget ≈ **80 GB/day** after carrier billing overhead. - each failover switch additionally costs **0.25–0.5 GB** of catch-up traffic. A mainnet node is at least as heavy. Practical advice (Polish market, 2026): for a **validator** setup a **truly unlimited** plan (~35 PLN/month) is the only stress-free option — a "150 GB" plan lasts ~2 days of a real outage and a "50 GB" plan under a day (node-only: ~2–3 days). Treat capped plans as short-blip budgets. - **Prepaid expiry**: prepaid SIMs need a periodic top-up to stay active — put it in your calendar. The failover's periodic health probes conveniently keep the SIM "in use" from the carrier's perspective. - **APN**: mainstream carrier SIMs configure themselves; some MVNOs need the APN set once in the modem's web UI. - **CGNAT is normal**: carrier networks block all inbound connections. The node works fine outbound-only — expectations below. ______________________________________________________________________ ## Distinct subnets — a hard requirement Every failover link must use a different IP subnet. The ZTE modems' LAN defaults to `192.168.0.0/24` — which is also the factory default of many home routers, so collisions are common. The watchdog **detects a collision and raises an alarm** (control-panel status banner + system journal) instead of switching traffic onto an ambiguous path. If you see the alarm: change your **router's** LAN subnet (e.g. to `192.168.1.0/24`), or the modem's, if its web UI allows it. ______________________________________________________________________ ## Setup, step by step 1. **Prepare the modem**: SIM inserted, PIN disabled. If the modem has a WiFi hotspot (MF79N, E8372h are "wingles"), **disable the hotspot** in its web UI — it is a security exposure, extra heat, and parasitic data on your metered SIM. The failover does not use it. 1. **Plug the modem into a USB 3.0 port** (short extension cable recommended). 1. Open the control panel (`control-panel.sh`) and press **`F` — Internet Failover (LTE)**. The status screen shows the modem (present/absent), **SIM PIN state**, network registration, signal, and data counters. 1. **Run the speed test** (`F` → `8`). It measures *through the modem interface*, shows RSRP/SNR signal readings, and prints an explicit **OK / BELOW MINIMUM** verdict against the 20/10 Mbit/s requirement. Judge a site only with this test — a browser speed test on your phone measures a different radio in a different spot. 1. **Enable failover** from the same menu. From this moment the feature is armed and fully automatic. 1. *(Optional)* **Add a WiFi rung** (`F` → WiFi setup): scan, pick a network, enter the password. On dual-band access points **prefer 5 GHz** (the band-preference option) — clients otherwise latch onto the louder-but-slower 2.4 GHz. Never select the LTE modem's own hotspot as the WiFi rung — that would be a "backup" riding the same SIM. Judge the site at more than one time of day LTE capacity swings 2–3× with cell load. The same modem in the same spot measured 21–45 Mbit/s down in the afternoon and 60 Mbit/s in the evening. One measurement is an anecdote, not a verdict — and **carrier choice dominates everything else**: if a site fails the minimum, a different carrier's SIM usually beats any antenna work. ### Weak signal? Escalate in this order 1. **Reposition the modem** (window side of the building can flip the verdict; watch RSRP/SNR in the speed-test readout — aim for RSRP above ~−90 dBm, SNR above ~13 dB). A terrible position doesn't just slow the link down, it wrecks latency (we measured a 7-second ping in one spot). 1. **External antennas** — see below. 1. **Try another carrier's SIM.** ### External antennas (TS-9) Some modems have connectors for external antennas — on this class of device they are almost always **TS-9** sockets, usually a pair of them hidden under small side covers (on the MF79N they are under the flip-open caps; retail listings often don't even mention them). TS-9 antennas are cheap (from ~45 PLN a pair) and easy to find in online shops — from small stubby sticks, through mid-size whips on a cable, up to desktop antennas you can place on a windowsill: With two sockets, connect **both** antennas (the second one serves MIMO — it is not a spare). An antenna on a cable also lets you keep the modem at the Pi while the antenna sits where the signal is. Re-run the speed test (`F` → `8`) after every change and watch RSRP/SNR — if antennas don't lift the site above the minimum, a different carrier's SIM usually will. ______________________________________________________________________ ## Verify it works (2 minutes) Do this once after setup — it is the same scenario the feature exists for: 1. Watch the failover status screen (`F`) or the panel dashboard. 1. **Pull the Ethernet cable.** Within seconds the active link changes to LTE (or WiFi, if provisioned); data-saving mode engages; the node keeps running. 1. Wait a few minutes, watching the node: peers drop to zero on the switch, then rebuild over LTE (a handful of peers on CGNAT is normal and sufficient). 1. **Plug the cable back in.** After ~2 minutes of confirmed-healthy Ethernet the system switches back automatically and data-saving mode ends. Every decision the watchdog makes is logged with its reason: `journalctl -t w3p-failover`. Machine-readable live state (which also feeds the panel): `/run/w3p-failover/status.json`. ______________________________________________________________________ ## What to expect while on LTE - **Fewer peers — by design of carrier networks.** Under CGNAT no inbound connections are possible, so the peer count settles around a dozen–two dozen instead of 150+ (bench: average ~20 over a 24 h LTE dwell). That is normal and sufficient; a validator needs only ~5–6 beacon peers to perform its duties. - **Port-forwarding rule of thumb**: opening the beacon's P2P ports on your **wired router** is worth it (bench: ~10–16 peers with ports closed → ~160 open). On **LTE it does nothing** — CGNAT blocks inbound regardless. - **Validators**: expect **at most 1–2 missed attestations per switch** and none during a stable dwell on a link meeting the 20/10 minimum. If the watchdog ever escalates (beacon-service restart, at most once per outage), the panel shows it as a brief service-state blip — that is the failover's safety valve doing its job, not a fault. The **validator service itself is never touched** by the failover. If you keep your validator keys on an encrypted (LUKS) volume with manual start, remember that it never auto-starts after a node reboot — a deliberate security property, unrelated to the failover (which never reboots the node). - **Data-saving mode** is automatic: upload shaped (anti-bufferbloat; download is never policed), automatic system updates paused until the wired link returns, all usage metered (`F` → data usage; daily/monthly history via vnstat). - **Do not start a resync while on LTE.** A fresh Geth snap-sync is 60+ GB — if the node needs a resync, wait for the wired link. ______________________________________________________________________ ## Troubleshooting | Symptom | Cause / fix | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Modem not detected, or `can't set config, error -110` in `dmesg` | Marginal USB seating or a USB 2.0 port. Re-seat firmly in a **USB 3.0** port (short extension cable helps). The system also retries mode-switching and power-cycles the port automatically. | | Modem detected, DHCP address assigned, **no data flows** | **SIM PIN is enabled** (the status screen shows PIN state) — disable it. Or: MVNO SIM needs the APN set once in the modem web UI. | | Bought an "E3372" and it doesn't work | Check `lsusb`: `3566:2001` = **Brovi** fake-Huawei from the avoid list — return it. | | **Subnet collision** banner in the panel | Your home LAN uses the same subnet as the modem (typically `192.168.0.0/24`). Change the router's LAN subnet, or the modem's if its UI allows. Failover refuses to arm the ambiguous link until resolved. | | Speed test says BELOW MINIMUM | Escalate: reposition (watch RSRP/SNR) → TS-9 antennas (MF79N) → different carrier. Re-test at different times of day. A single unit can also have a degraded radio — if a second modem is available, compare RSRP at the same spot. | | Terrible latency on LTE (multi-second pings) | Signal collapse causes bufferbloat. Move the modem first — one bad spot measured 5.9/0.1 Mbit/s with 7.4 s pings. | | `attest_risk` alarm while on LTE | The validator is active and the beacon has very few peers on this dwell. Usually transient during peer rebuild; if persistent, the link is too slow — check the speed test. | | Panel shows a beacon service restart during an outage | The escalation safety valve (at most once per outage). The validator itself is never restarted. | | WiFi rung connects at 2.4 GHz / slow | Set the 5 GHz band preference in the WiFi setup. Note the Pi's built-in radio tops out at ~200–250 Mbit/s real throughput — plenty for a failover rung. | | Frequent switching back and forth | The watchdog's flap protection latches onto the best healthy link automatically for 30 minutes, then re-evaluates. Check the wired link's actual health — flapping usually means a dying ISP link, not a failover problem. | ______________________________________________________________________ ## How it works under the hood (short version) Three layers, all shipped in the vOS image: 1. **A route-metric ladder** (Ethernet 100 > WiFi 300 > LTE 700): pure kernel/networkd configuration. Physical link loss fails over instantly with zero custom code. 1. **A watchdog daemon** (`w3p-failover.service`): probes each link (two independent anchors + DNS + gateway), applies hysteresis (demote after 20 s of failure, return after 120 s of health, flap protection), and covers the "cable fine, internet dead" case the ladder cannot see. A **chain-liveness veto** prevents false demotions while the node is saturating the link to catch up. 1. **The nudge**: on every switch, connections pinned to the dead path are closed (`ss -K` by source address) so Geth and Nimbus redial immediately instead of sitting deaf through kernel TCP timeouts — chain-head tracking typically returns within ~30–100 seconds of a switch. After every switch the watchdog verifies recovery by **liveness** (new connections on the new path + beacon head advancing), not by peer counts. If verification fails, it restarts the beacon service — once per outage, never the validator — then alarms. Details, design rationale and bench history live in the project's engineering notes. # Advanced Setup: Power over Ethernet (PoE) Power over Ethernet (PoE) is a networking feature that allows network cables to carry electrical power in addition to data. By using PoE, you can power your Web3 Pi Raspberry Pi using the same Ethernet cable that provides its network connection, eliminating the need for a separate USB-C power adapter. This can simplify cable management and potentially allow for centralized power backup if your network switch is connected to a UPS. ## Benefits of Using PoE - **Simplified Wiring:** Reduces cable clutter by combining power and data into a single Ethernet cable run to the Raspberry Pi. - **Flexible Placement:** Allows placing the Raspberry Pi further from power outlets, as long as an Ethernet cable can reach it. - **Centralized Power Backup:** If your PoE-providing network switch or injector is connected to a UPS (Uninterruptible Power Supply), your Raspberry Pi will also benefit from backup power. # Advanced Setup: Firewall Configuration (UFW) ## Understanding the Firewall Web3 Pi includes and enables **UFW (Uncomplicated Firewall)** by default to provide a baseline level of network security for your node. UFW is a user-friendly frontend for managing the underlying `iptables` firewall rules on Linux systems like Ubuntu. Its primary purpose is to control incoming and outgoing network traffic, ensuring that only necessary connections are allowed, thus reducing the potential attack surface of your device. ## Default Status and Policy - **Enabled by Default:** UFW is installed and enabled at the end of the Web3 Pi setup process. - **Default Incoming Policy:** `DENY` - All incoming connections are blocked unless explicitly allowed by a specific rule. - **Default Outgoing Policy:** `ALLOW` - All outgoing connections initiated by the Raspberry Pi are permitted. ## Default Allowed Incoming Ports The Web3 Pi installation script configures UFW to allow incoming traffic on the specific ports required for node operation, management, and monitoring based on your configuration choices during setup. The standard ports opened are: | Port | Protocol | Service | Purpose | | ----------------- | --------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `22` | TCP | SSH | Secure remote command-line access | | `80` | TCP | Installation Monitor / Status Page | [Viewing setup progress and basic status](https://docs.web3pi.io/monitoring/installation-monitor/index.md) | | `3000` | TCP | Grafana Dashboard | [Viewing node performance and health](https://docs.web3pi.io/monitoring/grafana/index.md) | | `5353` | UDP | mDNS (Avahi Daemon) | Hostname discovery (e.g., `web3pi.local`) | | `7197` | TCP | Basic System Monitor JSON API | [Programmatic access to monitoring data](https://docs.web3pi.io/monitoring/system-monitor/index.md) | | `8545` | TCP | Execution Client JSON-RPC (Geth) | Wallet connections | | `8546` | TCP | Execution Client WebSocket RPC (Geth) | WebSocket connections for dApps/tools | | `8551` | TCP | Execution Client Engine API (Geth) | Communication between EL & CL clients | | `9090` | TCP | Cockpit System Dashboard | [Web-based system management](https://docs.web3pi.io/management/cockpit/dashboard/index.md) | | `9000` (default) | TCP & UDP | Consensus Client P2P (Lighthouse/Nimbus) | Peer discovery and communication | | `30303` (default) | TCP & UDP | Execution Client P2P (Geth) | Peer discovery and communication | ## Checking Firewall Status and Rules You can view the current UFW status and the list of active rules by connecting via [SSH](https://docs.web3pi.io/management/ssh/index.md) and running the following commands: ``` sudo ufw status numbered ``` ## Adding or Removing Ports To add a new port, use the `ufw allow` command. For example, to allow incoming TPC traffic on port `12345`, run the following command: ``` sudo ufw allow 12345/tcp comment 'This port is used by XYZ service' ``` To remove a port, use the `ufw delete` command. It's recommended to use the `ufw status numbered` command to identify the rule number before deleting it. For example, to delete the rule with the number `100`, run the following command: ``` sudo ufw delete 100 ``` # Power Backup Solutions for Raspberry Pi 5 and Raspberry Pi 4 Web3 Pi UPS Web3 Pi now has its own smart DC UPS, designed specifically for Raspberry Pi 5 and the Web3 Pi ecosystem — instant failover, safe shutdown, and remote monitoring. See the [Web3 Pi UPS documentation](https://docs.web3pi.io/ups/index.md). ## Why Use Power Backup for an Ethereum Full Node? Running a full Ethereum node on Raspberry Pi, especially in projects like **Web3 Pi**, requires consistent and stable power. A power outage or fluctuation can result in corrupted data since the node continuously writes to storage. In addition, even if you live in a region with seemingly stable electricity, brief voltage dips or surges can occur unnoticed, potentially causing instability, freezing, or unexpected reboots of your Raspberry Pi. For optimal reliability, power backup systems should ideally cover not just the Raspberry Pi but the entire network path (e.g., routers and switches). However, even just powering the Raspberry Pi can significantly enhance stability. ## Backup Power Options for Raspberry Pi There are two primary solutions for providing backup power to Raspberry Pi: 1. **Conventional 230/110V UPS** 1. **Dedicated UPS for Raspberry Pi SBC** ### Conventional 230/110V UPS #### Advantages: - Widely available globally in various models and capacities. - Can power multiple devices, such as routers, switches, or multiple Raspberry Pis. #### Disadvantages: - Larger in size and often equipped with fans, which may produce noise. #### Recommended Model: - **Legrand UPS KEOR PDU (EAN: 3414971529380)** - Silent operation and tested for reliability. - [More details](https://www.legrand.pl/pl/e-katalog/produkty/ups-keor-pdu-fr8xfr-mont-rack-310330). ### Dedicated Raspberry Pi UPS #### Advantages: - Compact and silent. - Designed specifically for Raspberry Pi, often as a HAT or a small external device. - Equipped with popular 18650 cells for longer battery life, depending on the number of cells. - Can interface with Raspberry Pi to detect low battery levels and initiate safe shutdowns. #### Disadvantages: - Less commonly available but can be ordered online. #### Recommendations: ##### For Raspberry Pi 5: - **[Geekworm X1200 2-Cell 18650 5.1V 5A UPS HAT](https://geekworm.com/products/x1200)** - Designed specifically for Raspberry Pi 5. - Features: - Supports two 18650 batteries for extended runtime. - Output: 5.1V/5A for consistent power delivery. - Compact HAT form factor, easy to install. - [More information](https://geekworm.com/products/x1200). - **[Waveshare UPS Module 3S](https://www.waveshare.com/ups-module-3s.htm?sku=25603)** - Features: - Supports three 18650 batteries. - Smart power management with low-battery alert. - Compact external unit, easy to integrate. - [More information](https://www.waveshare.com/ups-module-3s.htm?sku=25603). ##### For Raspberry Pi 4: - **[Geekworm Raspberry Pi X728](https://geekworm.com/products/x728)** - Features: - Supports three 18650 batteries. - Integrated power management for safe shutdown. - Output: 5V/6A. - Compact design that mounts directly onto Raspberry Pi. - [More information](https://geekworm.com/products/x728). ### Installation and Setup The installation and configuration processes for these UPS devices are detailed on their respective product pages. Refer to the manufacturer's guides for precise instructions. ### Recommendation We highly recommend using a power backup solution to enhance the stability of your Ethereum node and reduce potential problems caused by power interruptions. For Ethereum **Solo Staking**, power backup is critical. A reliable power supply minimizes downtime, ensures data integrity, and helps avoid penalties related to missed attestations or blocks. # Monitoring Your Node Keeping an eye on your Ethereum node is crucial for ensuring it runs smoothly, stays synced, and uses resources efficiently. Web3 Pi includes several built-in tools to help you monitor different aspects of your setup: 1. **[Installation Monitor](https://docs.web3pi.io/monitoring/installation-monitor/index.md):** A simple web page exposed by your Pi that displays information about the system's setup status. While always available, it's **most useful during the initial installation** to track the progress of automated steps in real-time. 1. **[Grafana Dashboards](https://docs.web3pi.io/monitoring/grafana/index.md):** Provides detailed, graphical dashboards visualizing the performance and status of your Ethereum clients. Ideal for in-depth performance monitoring once the node is running. 1. **[LCD Display](https://docs.web3pi.io/monitoring/lcd/index.md):** If you've installed the optional LCD hardware, this small screen provides an at-a-glance view of key system information like IP address, hostname, CPU usage, and memory, directly on the device. 1. **[HTTP API](https://docs.web3pi.io/monitoring/system-monitor/index.md):** Offers a programmatic way to query node status and metrics. Useful for integration with custom scripts or external monitoring systems. Refer to the specific pages linked above for details on how to access and use each monitoring tool. # Basic Ethereum Node Monitor The Basic Ethereum Node Monitor plugin is responsible for monitoring the health and status of your Ethereum node. That data is then pushed to the InfluxDB database, which can be visualized in Grafana. ## Installation To install the Basic Ethereum Node Monitor plugin, navigate to the "Web3 Pi Updater" section in the Cockpit interface. Search for "Basic Ethereum Node Monitor" and install the plugin. On newer Web3 Pi releases, this plugin might be pre-installed by default. ## Usage Once installed, the Basic Ethereum Node Monitor plugin will start automatically. Open Grafana in your web browser (port 3000 by default) to view the collected data. The default username is **'admin'**, and the password is **'admin'**. It is **highly recommended** to change the password after the first login. ## Support For support and further assistance, join the [Web3 Pi Discord](https://discord.gg/aDMw5zeUZ4) community. # Installation Status Page The Installation Status plugin provides a comprehensive overview of the Web3 Pi installation process. It displays the status of each installation stage as well as any errors or warnings encountered during the process. ## Installation To install the Installation Status plugin, navigate to the "Web3 Pi Updater" section in the Cockpit interface. Search for "Installation Status" and install the plugin. On newer Web3 Pi releases, this plugin might be pre-installed by default. ## Usage Once installed, the Installation Status plugin will be accessible on port 80 of your Raspberry Pi. Simply open the URL in your web browser to view the status page. ## Disabling the Plugin If you no longer require the Installation Status plugin, you can disable it by stopping the `w3p_installation-status` service. To do this, navigate to the "Services" section in the Cockpit interface and stop the service. ## Source Code The source code for the Installation Status plugin can be found on [GitHub](https://github.com/Web3-Pi/installation-status). ## Support For support and further assistance, join the [Web3 Pi Discord](https://discord.gg/aDMw5zeUZ4) community. # LCD Dashboard To add an LCD dashboard to your Raspberry Pi, you will need: - A dashboard cover for mounting; - A suitable LCD display; - Software to run the LCD. ## Dashboard Cover The Web3 Pi LCD Dashboard project offers a suitable cover available for 3D printing. This is designed for installation of a colorful LCD in the Argon Neo 5 enclosure. We have designed our own 3D model of the enclosure cover with a space for the display. The assembly is simple, using snap-fits, with no tools required. The models are open-source, so anyone can print them on a 3D printer. The source code is also open-source, allowing users to add new functionalities, customize it to their needs, or add support for new displays. For more information, see [Web 3 Pi Dashboard](https://github.com/Web3-Pi/web3-pi-dashboard) documentation. ## LCD Display The LCD display should be 1.69" with ST7789V2 Driver. Suitable models are: - Waveshare 24382 - [See product page](https://www.waveshare.com/1.69inch-lcd-module.htm) - Seeed Studio 104990802 - [See product page](https://www.seeedstudio.com/1-69inch-240-280-Resolution-IPS-LCD-Display-Module-p-5755.html) ## Software The software is included in the Web3 Pi image, and can also be downloaded separately from the [Web 3 Pi Dashboard Project](https://github.com/Web3-Pi/web3-pi-dashboard). # Basic System Monitor (monitoring via HTTP API) The Basic System Monitor plugin is responsible for monitoring the health and status of your Web3 Pi. It exposes a simple HTTP API that can be queried to retrieve information about your device. ## Installation To install the Basic System Monitor plugin, navigate to the "Web3 Pi Updater" section in the Cockpit interface. Search for "Basic System Monitor" and install the plugin. On newer Web3 Pi releases, this plugin might be pre-installed by default. ## Usage Once installed, the Basic System Monitor plugin will start automatically. You can query the status of your Web3 Pi by calling the HTTP API endpoint on port 7197 (by default). The output should look similar to this: ``` { "host_name": "eop-1", "num_cores": 4, "cpu_percent": 30, "mem_total": 8323276800, "mem_used": 6859583488, "mem_free": 386887680, "mem_percent": 85.4, "swap_total": 17179865088, "swap_used": 7224090624, "swap_free": 9955774464, "swap_percent": 42, "disk_used": 1359481831424, "cpu_temp": 58.95, "net_upload": 510982.969251317, "net_download": 702530.988724869 } ``` ## Support For support and further assistance, join the [Web3 Pi Discord](https://discord.gg/aDMw5zeUZ4) community. # Cockpit Dashboard ## What is Cockpit? Web3 Pi comes with [**Cockpit**](https://cockpit-project.org/) pre-installed. Cockpit is a free, open-source, web-based graphical interface for servers and Linux systems. It allows you to monitor and administer your Raspberry Pi's underlying operating system (Ubuntu) directly from your web browser. Think of it as a user-friendly dashboard for managing the system itself. ## What Can You Do with Cockpit on Web3 Pi? While Grafana dashboards focus specifically on monitoring your Ethereum node clients (EL/CL), Cockpit focuses on the **operating system** level. Common uses include: - Checking CPU, RAM, and network usage trends. - Viewing available disk space on your system drive and attached USB drive. - Inspecting system logs (`journald`). - Checking the status of system services (be cautious about stopping essential services!). - Viewing network interface configurations. ## How to Access Cockpit 1. Find the **IP address** or **hostname** of your Raspberry Pi. - [How to find your node's IP address or hostname](https://docs.web3pi.io/support/cheatsheet/#how-to-find-your-nodes-ip-address-or-hostname) 1. Navigate to `http://:9090` (replace `` with the actual IP address or hostname). 1. You may see a security warning because Cockpit uses a self-signed SSL certificate by default. It's safe to proceed (usually under an "Advanced" or "Proceed anyway" option). 1. Log in using the username `ethereum` and password you selected. If this is your first time accessing your Web3 Pi, use the default password. You will be required to change the password upon first login. Note The default password is `ethereum`. Change it as soon as possible to prevent unauthorized access. Now you can explore the Cockpit interface and monitor your Web3 Pi's system health! ## Official Web3 Pi Plugins The Web3 Pi project maintains a number of official plugins for Cockpit. - [Web3 Pi Updater](https://docs.web3pi.io/management/cockpit/web3-pi-updater/index.md) - Manages Web3 Pi and Ethereum packages. - [Web3 Pi Link](https://docs.web3pi.io/management/cockpit/web3-pi-link/index.md) - Allows you to expose your Ethereum node (and more) to the internet. - [Script Runner](https://docs.web3pi.io/management/cockpit/web3-pi-script-runner/index.md) - Allows you to run pre-installed scripts on your Web3 Pi. - [Basic Ethereum Node Monitor](https://docs.web3pi.io/monitoring/grafana/index.md) - Monitors your Ethereum node (EL/CL) and pushes data to InfluxDB. - [Basic System Monitor](https://docs.web3pi.io/monitoring/system-monitor/index.md) - Exposes a simple HTTP API for monitoring your Web3 Pi. - [LCD Dashboard](https://docs.web3pi.io/monitoring/lcd/index.md) - Adds an LCD display to your Web3 Pi. - [Installation Status](https://docs.web3pi.io/monitoring/installation-monitor/index.md) - Provides a comprehensive overview of your Web3 Pi installation. # Web3 Pi Link Web3 Pi Link is a Cockpit plugin enabling secure exposure of Raspberry Pi services to the internet. It functions as a reverse proxy tunnel, eliminating the need for manual port forwarding. This document provides technical details for developers using Web3 Pi Link. ## Core Functionality Web3 Pi Link establishes a persistent, encrypted tunnel between your Raspberry Pi and a Web3 Pi managed server. This tunnel allows external access to services running on your Pi without direct exposure or complex network configuration. The plugin manages the tunnel lifecycle and provides a simplified configuration interface within Cockpit. ## Key Features - **HTTP/WebSocket Proxy:** Supports forwarding HTTP and WebSocket traffic from the Raspberry Pi to a public-facing address. *Note: Other protocols like SSH are currently not supported.* - **Automatic HTTPS:** All tunnels are automatically secured with HTTPS, even if the service on the Raspberry Pi uses HTTP internally. - **Automatic Reconnection:** The plugin automatically re-establishes the tunnel in case of network interruptions. - **Cockpit Integration:** Configuration is managed entirely through the Cockpit web interface. - **Subdomain Routing:** Each service is assigned a unique subdomain (`yourname.web3pi.link`) for easy access. ## Technical Architecture The plugin creates a reverse proxy tunnel. When a request arrives at `yourname.web3pi.link`, it's routed through the Web3 Pi infrastructure, through the secure tunnel to the specified port on your Raspberry Pi. The tunnel client, running on the Raspberry Pi, establishes an outbound connection to the Web3 Pi servers, so there is no need to open any specific ports on your Pi. ## Installation and Configuration ### Prerequisites - A Raspberry Pi with Web3 Pi installed and operational. - Cockpit web interface access. - Network connectivity allowing outbound connections. *Note: No specific firewall rules are required as the connection is initiated from the Raspberry Pi.* ### Installation Steps 1. **Install via Cockpit:** Access the Cockpit web interface and navigate to the "Web3 Pi Updater" section. Search for "Web3 Pi Link" and install the plugin. Make sure to refresh the page after the installation is complete. Newer Web3 Pi versions may have this plugin already installed by default. 1. **Configuration:** The Web3 Pi Link plugin will appear in the Cockpit navigation. - **Local Port:** Specify the TCP port on your Raspberry Pi that you want to expose (e.g., `3000`, `8545`, `9090`). This is the port your HTTP service is listening on. - **Subdomain:** Choose a unique subdomain name. This will be used to construct the public-facing URL (`yourname.web3pi.link`). The subdomain must be globally unique. A valid subdomain must begin with a letter or number and can contain lowercase letters, numbers, and hyphens. ## Troubleshooting and Debugging - **Verify Service Status:** Check that the Web3 Pi Link service is enabled and running. You can do this by navigating to the "Services" section in the Cockpit interface and searching for "web3-pi-link". - **Network Connectivity:** Ensure the Raspberry Pi has outbound internet access. - **HTTPS Issues:** While Web3 Pi Link automatically provides HTTPS, ensure your application handles redirects correctly if it expects HTTPS. ## Security Considerations - **Secure Your Application:** Web3 Pi Link provides a secure tunnel with automatic HTTPS, but it's crucial to secure your application. Implement proper authentication, authorization, and input validation to prevent vulnerabilities. - **Regular Updates:** Make sure to always keep your Web3 Pi software up to date with the latest security patches. You can download the latest updates to each plugin from the "Web3 Pi Updater" section in the Cockpit interface. - **Monitor Logs:** Regularly monitor application logs for suspicious activity. ## Support For support and further assistance, join the [Web3 Pi Discord](https://discord.gg/aDMw5zeUZ4) community. # Script Runner Script Runner is a Cockpit plugin that provides a user-friendly interface for executing pre-installed scripts on your Web3 Pi. This allows for easy access to common utilities and diagnostic tools directly from the Cockpit web interface. ## Installation The Script Runner plugin is installed via the "Web3 Pi Updater" section in the Cockpit interface. Search for "Script Runner" and install the plugin. Make sure to refresh the page after the installation is complete. On newer Web3 Pi releases, this plugin might be pre-installed by default. ## Usage The Script Runner plugin is located in the Cockpit navigation menu. Upon opening, you will see a list of available scripts. ### Running a Script 1. **Select a Script:** Click on the desired script from the list. 1. **View Script (Optional):** Click on the "Read File Contents" button to inspect the script's contents. 1. **Run Script:** Click the "Run" button to execute the script. 1. **View Output:** The script's output will be displayed in a terminal window within the plugin. ## Troubleshooting - **Script Execution Errors:** Check the script's output for error messages. - **Missing Scripts:** If a script is missing, ensure your Web3 Pi installation is up-to-date. Navigate to the "Web3 Pi Updater" section in the Cockpit interface and search for "Script Runner". ## Support For support and further assistance, join the [Web3 Pi Discord](https://discord.gg/aDMw5zeUZ4) community. # Web3 Pi Updater The Web3 Pi Updater plugin provides a centralized interface for managing Web3 Pi packages and essential Ethereum node dependencies. This tool allows you to easily list, update, and install software directly from the Cockpit web interface. ## Usage The Web3 Pi Updater plugin is located in the Cockpit navigation menu. ### Packages List Packages are separated into two categories: Web3 Pi Official Packages and Ethereum Packages. The former are maintained by the Web3 Pi team and provide additional functionality for your device, while the latter are maintained by their respective developers and are essential for running a node. ### Refresh Packages List Web3 Pi packages are distributed from our apt repository. To ensure that your device is up to date with the latest packages, click the **Refresh packages list** button. This will update the list of available packages and give you the option to install or update them. Note The **Refresh packages list** button has the same effect as running `sudo apt update` on the command line. ### Install or Update Packages To install a package, click the **Install** button next to the package name. To update an existing package, click the **Update** button next to the package name. Note After installing a new cockpit plugin, you may need to refresh your browser tab to see the new plugin in the navigation menu. ## Notes - Package installations and updates may require administrative privileges. - Ensure your Web3 Pi has a stable internet connection during package operations. - Regularly check for updates to maintain optimal performance and security. ## Support For support and further assistance, join the [Web3 Pi Discord](https://discord.gg/aDMw5zeUZ4) community. # Web3 Pi WelcomeBox ## The Complete Starter Kit for Ethereum Nodes on Raspberry Pi The Web3 Pi WelcomeBox is designed to be an all-in-one package, providing you with everything you need to launch your own Ethereum node on a Raspberry Pi 5 with a seamless setup experience. It bundles compatible, tested hardware components to save you the time and effort of sourcing them individually. ## What’s Inside? The WelcomeBox includes the following components: | Photo | Product name | Store Link | | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Raspberry Pi 5 - 8GB RAM** The heart of Web3 Pi. Powered by an efficient ARM processor, it delivers high performance while maintaining energy efficiency. | [TME](https://www.tme.eu/pl/en/details/sc1112/raspberry-pi-minicomputers/raspberry-pi/raspberry-pi-5-8gb-ram/) / [Kamami](https://kamami.pl/en/raspberry-pi-5/1187962-raspberry-pi-5-8gb-ram-24ghz-wifi-dualband-bluetooth-pcie-20-2x-csidsi-2x-usb-30-2x-4kp60-microhdmi-5056561803326.html) / [Botland](http://botland.store/raspberry-pi-5-modules-and-kits/23905-raspberry-pi-5-8gb-5056561803326.html) | | | **Official Raspberry Pi 5 power supply** Official Raspberry Pi 5 power adapter with a USB-C connector. Delivers up to 27W for stable and reliable operation. | [TME](https://www.tme.eu/pl/en/details/sc1408/raspberry-pi-acessories/raspberry-pi/rpi-27w-usb-c-power-supply-black-eu/) / [Kamami](https://kamami.pl/en/power-supplies/1187966-sc1157-raspberry-pi-27w-usb-c-power--5056561803418.html) / [Botland](https://botland.store/raspberry-pi-5-power-supply/23907-raspberry-pi-27w-usb-c-power-supply-official-51v-5a-psu-for-raspberry-pi-5-black-5056561803418.html) | | | **2TB m.2 storage:** Lexar NM790 or Goodram PX700 A high-speed 2TB NVMe storage for fast blockchain synchronization. Designed for low power consumption, high performance, and long life. | Lexar NM790: [Product page](https://www.lexar.com/global/products/Lexar-NM790-M-2-2280-PCIe-Gen-4x4-NVMe-SSD/) / [Morele.net](https://www.morele.net/dysk-ssd-lexar-nm790-2tb-m-2-2280-pci-e-x4-gen4-nvme-lnm790x002t-rnnng-12848184/) Goodram PX700: [Product page](https://www.goodram.com/produkty/goodram-px700-ssd/) / [Morele.net](https://www.morele.net/dysk-ssd-goodram-px700-2tb-m-2-2280-pci-e-x4-gen4-nvme-ssdpr-px700-02t-80-13134971/) | | | **Argon Neo 5 NVMe enclosure** A compact enclosure with active cooling. It looks sleek, provides excellent thermal management, and fits in any corner. | [Kamami](https://kamami.pl/obudowy-do-raspberry-pi/1192348-argon-neo-aluminum-alloy-case-for-raspberry-pi-5-built-in-cooling-fan-optional-for-m-2-nvme-interf-5906623488377.html) / [Botland](https://botland.store/raspberry-pi-5-cases/24397-argon-neo-5-m2-nvme-pcie-case-for-raspberry-pi-5-with-fan-and-heatsink-aluminum-black-6974297862181.html) | | | **microSD Card** High-speed microSD card (preferably 32GB or larger) for storing the operating system and node data files, with plenty of space for future expansions. | [Kamami](https://kamami.pl/en/memory-cards/1185040-karta-pamieci-microsd-kingston-canvas-select-plus-64gb-c10-a1-740617298963.html) / [Botland](https://botland.store/microsd-sd-cards/20229-memory-card-goodram-ir-m2aa-microsd-64gb-170mbs-uhs-i-class-u3-with-adapter-5908267961339.html) | | | **Color LCD Dashboard** A high-quality LCD screen designed to provide real-time insights into your node and operating system status. | [Kamami](https://kamami.pl/en/tftips-displays/1184835-1-69inch-lcd-display-module-240-280-resolution-spi-interface-ips-262k-colors-5906623427451.html) / [Botland](https://botland.store/lcd-tft-ips-displays/23391-lcd-ips-169-display-240x280px-spi-interface-262k-waveshare-24382.html) | | | **3D Printed Cover** A custom-designed plastic cover, 3D printed specifically for Web3 Pi. It allows for mounting the LCD display while providing a sleek and functional finish. | [3D models](https://github.com/Web3-Pi/web3-pi-dashboard/tree/main/docs/3D_Model) | | | **Ethernet Cable cat. 5e** A 2-meter high-quality Ethernet cable, included to complete the set. | [TME](https://www.tme.eu/pl/en/details/pcu5-10cc-0200-bk/rj45-cables/lanberg/) / [Kamami](https://kamami.pl/en/ethernet-cables/1181917-patchcord-cat-5e-utp-2m-black-fluke-passed-lanberg-5901969406726.html) / [Botland](https://botland.store/utp-cat-5e/12852-lanberg-ethernet-patchcord-utp-5e-2m-black-5901969406726.html) | | | **microSD Card Reader:** Ugreen CR127 A handy tool for flashing your microSD card with the operating system and node data. | [Ugreen](https://www.ugreen.pl/en/products/adapters/usb-a/ugreen-usb-adapter-card-reader-sd-microsd-black-141330) / [Morele.net](https://www.morele.net/czytnik-ugreen-cr127-usb-3-0-20250-6697738/) | | | **microHDMI-HDMI cable** Not required for running Web3 Pi, but invaluable for troubleshooting and initial setup. | [TME](https://www.tme.eu/pl/en/details/sc0532/raspberry-pi-acessories/raspberry-pi/micro-hdmi-m-to-hdmi-a-m-cable-2m-black/) / [Kamami](https://kamami.pl/przewody-audio-wideo-do-raspberry-pi/584432-oficjalny-przewod-microhdmi-hdmi-do-raspberry-pi-2m-czarny-5056561800714.html) / [Botland](http://botland.store/raspberry-pi-4b-audio-video-cables/16337-microhdmi-cable-hdmi-20-original-for-raspberry-pi-45-2m-black-5056561800714.html) | | | **Pliers** Handy pliers that make hardware assembly easier. Ideal for gripping small components and included for your convenience. | [TME](https://www.tme.eu/pl/en/details/neo-01-102/universal-pliers/neo-tools/01-102/) / [Kamami](https://kamami.pl/en/pliers/581378-straight-elongated-pliers-110-mm-vorel-42303-5906083423031.html) / [Botland](https://botland.store/straight-pliers/1518-straight-pliers-125mm-vorel-42303-black-5906083423031.html) | | | **Screwdrivers: PH0 and flat 3mm** A set of screwdrivers to tighten screws and secure components. Included to ensure you have everything needed to set up Web3 Pi. | PH0: [TME](https://www.tme.eu/pl/en/details/pg-t065/screwdrivers/pg-tools/pgt065/) flat: [TME](https://www.tme.eu/pl/en/details/pg-t071/screwdrivers/pg-tools/pgt071/) | *(Note: Exact components like storage brand or specific tool types may vary slightly based on availability, but will meet the required specifications.)* ______________________________________________________________________ ## Assembly and Setup Follow the instructions in the [Full Setup Guide](https://docs.web3pi.io/setup/single-mode/software-setup/index.md) to assemble and configure your Web3 Pi. ______________________________________________________________________ ## Availability *Coming soon* # Solo Staking with Web3 Pi Under Development & High Risk Web3 Pi does not currently offer official support for staking configurations. Proceed at your own risk. While Web3 Pi provides the necessary Execution and Consensus client foundation, configuring it securely and reliably for staking requires significant technical expertise beyond the standard setup. You are welcome to explore configuring your node for staking independently, but please be aware: - **This is an advanced procedure.** - Web3 Pi **does not currently offer official support** for staking configurations. - You proceed **entirely at your own risk.** Mistakes can lead to financial penalties (slashing). We strongly recommend thoroughly understanding the responsibilities and substantial risks involved before attempting solo staking. ➡️ **[Review Staking Risks and Considerations](https://docs.web3pi.io/introduction/staking/index.md)** # Web3 Pi Transactions Firewall TxFirewall is a tool that enhances the security of interactions with the Ethereum network through local RPC endpoints. It is designed to work with the [Ethereum On Raspberry Pi](https://github.com/Web3-Pi/Ethereum-On-Raspberry-Pi) suite. At its core, TxFirewall functions as a local transaction-intercepting proxy server. It acts as an intermediary between the user's wallet (e.g., MetaMask) and the RPC endpoint of their own W3P Ethereum node. Technically, TxFirewall listens on a specific local port configured in the wallet. When the wallet sends an RPC request, TxFirewall intercepts it. Simple data read calls (like `eth_getBalance`) can be passed directly to the W3P node. However, critical calls like `eth_sendTransaction` are halted and subjected to a verification process. Crucially, this entire process happens locally on the W3P device or the user's machine, before the transaction is broadcast to the Ethereum network. ## Installation The firewall can be installed manually on any computer by following the instructions available at Github repository: [Web3 Pi Transaction Firewall](https://github.com/Web3-Pi/ethereum-transactions-firewall). However, Web3 Pi Transaction Firewall is part of the Web3 Pi ecosystem, and the recommended installation method is through the **Cockpit** management system, accessible via the **Web3 Pi Updater** plugin. This installation approach automatically sets up the firewall along with the cockpit plugin, providing a complete graphical interface for firewall management. You can easily install Transaction Firewall on your Raspberry Pi by clicking **Install** in the Web3 Pi Updater plugin. In this version, the entire package is installed with initial configuration. The firewall is installed as a systemd service with appropriate permissions and configuration paths to ensure it uses the local Ethereum RPC client on your Web3 Pi by default. Additionally, the package includes a Cockpit plugin for complete management and control of the firewall. ## Configuration After installation, a new item labeled **Web3 Pi Tx Firewall** will appear in the Cockpit Menu. The firewall configuration window looks as follows: Note You must have administrator privileges enabled to use the Web3 Pi Tx Firewall. Otherwise, you will see a warning message: ### Main settings The top menu of the panel provides options to stop and start the firewall service, as well as configure basic settings: - **`Server Port`**: Port number where the main application serves the web interface for users to verify transactions.\ **Default:** `8454` - **`Proxy Port`**: Port number used for the proxy service. Used by RPC clients such as Metamask.\ **Default:** `18500` - **`WSS Port`**: Port number dedicated for WebSocket connections used between the web application and the firewall.\ **Default:** `18501` - **`RPC Endpoint`**: The RPC endpoint used to communicate with your Ethereum or blockchain node.\ **Default:** `http://localhost:8545` - local Ethereum node in Web3 Pi - **`Interactive Mode Timeout`**: Timeout duration for user decision in interactive mode (in seconds).\ **Default:** `60` Note Changing these settings requires a restart of the firewall service. #### Opening ports in OS firewall The default firewall application ports are blocked by the operating system firewall (USW). This is indicated by an icon next to the listed ports. To use the Tx firewall, you need to unblock these ports. You can do this manually via the [USW CLI](/#todo) or by clicking the lock icon next to each port. Warning If the ports are not open, attempting to access the firewall's frontend application will result in the following message: ### Authorized address In this table, you can add, edit or delete addresses that you recognize and set an appropriate name for them. This name will be displayed in the transaction verification window. It can be either an Ethereum account address or a contract address. ### Known contracts In this table, you can define contracts that you recognize, including both their names and ABIs. This configuration will be used to decode transaction parameters. In the verification window, the name of the smart contract function being called and its argument names will be displayed. Additionally, if the argument type is `address`, it will be displayed with the appropriate name if it is found as an authorized address. ### Client configuration (Metamask) You can configure any Ethereum RPC client - any wallet (including hardware wallets), or it can be an application using blockchain. This example demonstrates configuration instructions for the popular Metamask wallet. For this purpose, you need to: To navigate to the network configuration window in Metamask, follow [the official Metamask instructions](https://support.metamask.io/configure/networks/how-to-add-a-custom-network-rpc/#adding-or-editing-rpc-urls) and then fill in the required fields. Note You should use as `Default RPC URL` a URL consisting of your Pi's hostname or IP address and the port defined in the configuration as `Proxy Port` ## Usage To use the Tx Firewall, open the frontend application by clicking the **Open Firewall App** button in the top menu. Warning The Firewall in its current version works exclusively in interactive mode, which means that transactions will only be verified and rejected when the frontend application window is active. If the window is not running,\ **all** (!) transactions will be forwarded to the specified RPC node. ### Frontend App After opening the application, you can monitor transactions in the window: If for any reason you lose the connection, you should see a notification message. Warning Remember! In such a situation, the Firewall operates in mode: Accepts everything! #### Validating transaction ##### Simple transfer During a simple funds transfer from one account to another, the transfer transaction will be displayed in the application window with properly tagged addresses if they have been defined as *Authorized Addresses*. You can accept or reject the displayed transaction within the time shown on the screen. Note If you don't make a decision within the specified time, the transaction will be automatically rejected! The decision time is set in the `Interactive Mode Timeout` parameter. ##### Contract call If you execute a transaction on a smart contract - for example, an ERC-20 token transfer like Golem Network Token - by calling the transfer function on a specific smart contract, it will be decoded and displayed in the application window. Note Pay attention that the address fields have been tagged with names defined in the `Authorized Addresses` and `Known Contract` tables. If these definitions weren't present, the labels would display as `Unknown`. If you make a transaction on a contract that hasn't been defined in the `Known Contracts` table, a data field with undecoded transaction data in hexadecimal format will appear in the verification window. Note That's why it's important to define contract ABIs for proper transaction verification! ###### Predefined Standard Interfaces If a contract address is not matched with any entries in the `Known Contracts` table, the firewall attempts to recognize and match the contract data against a set of predefined standard interfaces: - **Main standards**: - ERC20 - Standard interface for fungible tokens - ERC721 - Standard interface for non-fungible tokens (NFTs) - ERC1155 - Multi-token standard - ERC4626 - Tokenized vault standard - **Popular extensions**: - ERC20Burnable - ERC20 extension allowing token burning - **Popular utility contracts**: - Ownable - Contracts with ownership functionality - AccessControl - Contracts with role-based access control All these interfaces are imported from the [OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts) library, which provides secure and community-vetted implementations of common smart contract standards. This automatic detection allows the firewall to correctly parse and display transaction data. Contract will be tagged as `Possible Interface: ...` ### Logs While operating and using the firewall, you can view service logs in the Cockpit panel, where firewall activities are recorded: By clicking on a specific log entry, you can see its details. Logs are stored in JSON format: ``` { "level": 30, "time": "2025-04-25T16:54:57.819Z", "pid": 33525, "hostname": "eop-1", "transaction": { "id": "0xd1490ab481cb7c2d7713a98fa52878300d04ae750b73ed42e28724387aa840a1", "from": "0x19ee20338a4c4bf8f6aebc79d9d3af2a01434119", "to": "0x7dd9c5cba05e151c895fde1cf355c9a1d5da6429", "value": "0", "data": "0xa9059cbb000000000000000000000000de07073781cadad26053b6d36d8768f0bd283751000000000000000000000000000000000000000000000000001c6bf526340000", "labelFrom": "Bob", "labelTo": "GLM Token Contract", "txType": "contract-call", "contractInfo": { "address": "0x7dd9c5cba05e151c895fde1cf355c9a1d5da6429", "labelAddress": "Golem Contract", "functionName": "transfer", "args": [ { "name": "recipient", "type": "address", "value": "0xdE07073781CADaD26053b6d36D8768f0bD283751", "label": "Alice" }, { "name": "amount", "type": "uint256", "value": "8000000000000000" } ] } }, "msg": "Transaction accepted" } ``` ## Security ### Limitations Currently, only the Interactive Mode of the Firewall is available. This means that transaction verification can only be performed when the frontend application is open. - If the web page is not open, the service automatically forwards all requests to the configured RPC endpoint - Only one web page instance may be opened at a time - Opening an additional webpage instance drops the old connection and redirects all queries to the current page - This is an asynchronous service, but it serves only one request at a time - Requests are not queued - New requests sent during the processing of a previous one are automatically forwarded to the configured RPC endpoint ### More about threats... You can read more about the need to use the Firewall together with Web3 Pi on our blog [Fortify Your Ethereum Journey Web3 Pi Transaction Firewall](https://www.web3pi.io/blog/ethereum-txfirewall) # Connect Your Wallet to Your Node One of the significant advantages of running your own Ethereum node with Web3 Pi is the ability to use it as a private and trusted backend for your crypto wallets, such as MetaMask. Instead of relying on default public RPC endpoints provided by wallet developers or third parties, you can point your wallet directly to your own node running on your local network. ## Why Connect Your Wallet to Your Own Node? - **Enhanced Privacy:** When you use public RPC endpoints, the provider *could* potentially log your IP address and the wallet addresses you query. By using your own node, your transaction lookups and balance checks stay within your local network, significantly improving your privacy. - **Increased Reliability:** Public endpoints can sometimes become congested or experience downtime. Your own node provides a dedicated resource that you control, potentially offering more consistent availability (assuming your node and internet connection are stable). - **Trust Minimization:** You are directly querying the Ethereum blockchain state as validated by *your* node, rather than trusting a third-party provider's node. This aligns with the core principles of decentralization. - **No Rate Limiting:** Public RPCs often have rate limits to prevent abuse. Your own node doesn't impose such external limits (though it's still bound by its own processing capabilities). ## Prerequisites 1. **Web3 Pi Node Running:** Your Raspberry Pi must be powered on, connected to your network, and the Ethereum Execution Client must be running and fully synced with the network you intend to use (e.g., Mainnet, Sepolia). 1. **Wallet Installed:** You need a wallet that supports custom RPC endpoints (MetaMask is a common example). 1. **Node's Local IP Address or Hostname:** You need to know the IP address (e.g., `192.168.1.123`) or hostname (e.g., `web3pi.local`) of your Raspberry Pi on your local network. Consult the [Cheatsheet](https://docs.web3pi.io/support/cheatsheet/#how-to-find-your-nodes-ip-address-or-hostname) if you're not sure how to find it. ## Finding Your Node's RPC Address Your Execution Client exposes an RPC endpoint that wallets can connect to. You can access it in a few ways: 1. **Local IP Address:** Use your node's IP address on your local network. - Format: `http://:` - Default Port: `8545` - Example: `http://192.168.1.123:8545` - *Use Case: Connecting from devices on the same local network (Wi-Fi).* 1. **Local Hostname:** Use the hostname assigned to your node. - Format: `http://:` - Default Port: `8545` - Example: `http://web3pi.local:8545` - *Use Case: Connecting from devices on the same local network (Wi-Fi). Requires local DNS resolution (mDNS/Bonjour) to work.* 1. **Web3 Pi Link Address (Remote Access):** If you have set up [Web3 Pi Link](https://docs.web3pi.io/management/cockpit/web3-pi-link/index.md), you can use the secure public HTTPS URL provided by the service. - Format: `https://.web3pi.link` - *(Note: Web3 Pi Link handles the port mapping and provides a standard HTTPS port 443 endpoint).* - Example: `https://my-awesome-node.web3pi.link` - *Use Case: Connecting from anywhere, including outside your local network (e.g., when you're not home).* Choose the appropriate address based on how and where you want to connect to your node. ## Configuration Steps (MetaMask Example) MetaMask doesn't allow adding a new network with the same Chain ID as an existing one (like Mainnet `1`, Sepolia `11155111`, etc.). Therefore, to use your node for these standard networks, you need to **edit the existing network settings** in MetaMask. **Editing an Existing Network (e.g., Mainnet, Sepolia):** 1. **Open MetaMask:** Unlock your MetaMask extension. 1. **Network Dropdown:** Click on the network selection dropdown menu (top-left). 1. **Open the Edit Network Wizard:** Click the "Edit" button in the network dropdown. 1. **Update RPC URL:** Locate the "Default RPC URL" field and add a new RPC URL. - For local access: `http://web3pi.local:8545` or `http://192.168.1.123:8545` (Use `http`) - For remote access via Web3 Pi Link: `https://my-awesome-node.web3pi.link` (Use `https`) 1. **Select Your RPC** Now that you've added your RPC endpoint, select it from the dropdown menu. 1. **(Optional) Rename the network:** You can rename the network to something more descriptive (e.g., `Web3 Pi Mainnet` or `Ethereum Mainnet (Web3 Pi)`). 1. **Save:** Click the "Save" button. Your MetaMask wallet is now configured to communicate directly with your own Web3 Pi Ethereum node using the specified RPC URL. ## Important Considerations - **Local vs. Remote:** Remember to use the local `http://...:8545` address only when your wallet device is on the same network as the Pi. Use the `https://....web3pi.link` address for access from anywhere else. - **Security (Manual Exposure):** The default Web3 Pi setup exposes the RPC port (`8545`) only locally. **Do not manually configure your router/firewall to expose port 8545 directly to the public internet** unless you implement robust security. Web3 Pi Link is the recommended way to achieve secure remote access. # Cheatsheet This cheatsheet provides a quick reference for commonly used commands, ports, credentials, and configurations for your Web3 Pi node. ## Default Credentials **SSH Access:** | Username | Password | | ---------- | ---------- | | `ethereum` | `ethereum` | *Note: You are required to change this password upon first SSH login.* **Grafana Dashboard:** | Username | Password | | -------- | -------- | | `admin` | `admin` | *Note: You will be prompted to change this password upon first Grafana login. It is highly recommended to do so.* ## Common Network Ports | Port | Service / Description | Access Method | | ------- | ------------------------------------- | ------------- | | `22` | SSH | SSH | | `80` | Installation Monitor / Status Page | HTTP | | `3000` | Grafana Dashboard | HTTP | | `5052` | Lighthouse HTTP REST API | HTTP | | `5353` | mDNS (Avahi Daemon) | mDNS | | `7197` | Basic System Monitor JSON API | HTTP | | `8008` | InfluxDB HTTP API | HTTP | | `8545` | Execution Client JSON-RPC (Geth) | HTTP | | `8546` | Execution Client WebSocket RPC (Geth) | HTTP | | `8551` | Execution Client Engine API (Geth) | HTTP | | `9000` | Consensus Client P2P (Lighthouse) | TCP/UDP | | `9000` | Consensus Client P2P (Nimbus) | TCP/UDP | | `9090` | Cockpit System Dashboard | HTTPS | | `30303` | Execution Client P2P (Geth) | TCP/UDP | ## How to find your nodes ip address or hostname - **Hostname:** Use the hostname you chose during image creation (e.g., `web3pi.local`, `eop-1.local`). Check via SSH with `hostname`. - **IP Address:** Check your router's admin panel or use network scanning tools to find the IP address assigned to your Raspberry Pi. - **LCD Display:** If installed, the [LCD Dashboard](https://docs.web3pi.io/monitoring/lcd/index.md) shows the current IP address and hostname. ## Log files - **Web3 Pi Logs:** `/var/log/web3pi.log` - **rc.local logs:** `/root/first-run.flag` ## Internet connectivity ### Bandwidth To achieve optimal synchronization performance, your internet connection should have a download bandwidth of at least 160 Mb/s (20 MB/s). The upload requirement, however, is significantly lower. The synchronization process with the Ethereum mainnet requires downloading approximately 1.2 TB of data. [1.1 TB download, 25 GB upload - October 2024] So please be cautious if your internet connection is metered. A slower internet connection will still function, though the synchronization process will take longer. While upload and download speeds are important, they are only one factor in determining the quality of your connection. Ideally, a stable connection with low latency (ping) is recommended. For optimal performance, having a static public IP address is beneficial, but it is not strictly necessary. ### WIFI The default and recommended method for connecting the Raspberry Pi in the Web3 Pi project is via a wired Ethernet connection with automatic DHCP configuration. However, you can also connect Raspberry Pi 4/5 to the internet using the built-in WiFi module. To do so, in Raspberry Pi Imager, you must provide the SSID and password for your WiFi network. Although using WiFi is possible, we strongly recommend using a wired connection. Over time, WiFi may lead to issues with connection stability and bandwidth performance. Note If you are using WIFI, do not connect the Ethernet cable to the Raspberry Pi. ## Common Monitoring & Management Commands (via SSH) Many system management and logging commands require elevated privileges. Use `sudo` before the command as shown below. You will be prompted for the `ethereum` user's password the first time you use `sudo` in a session. Replace `` with the actual service: `w3p_geth`, `w3p_lighthouse-beacon`, or `w3p_nimbus-beacon`. ### Service Management (systemd) - **Check Status:** See if a service is running and view recent log snippets. ``` sudo systemctl status # Example: Check Geth status sudo systemctl status w3p_geth ``` - **Start Service:** ``` sudo systemctl start ``` - **Stop Service:** ``` sudo systemctl stop ``` - **Restart Service:** (Stop and then start) ``` sudo systemctl restart ``` - **Enable Service:** (Start automatically on boot - usually pre-configured) ``` sudo systemctl enable ``` - **Disable Service:** (Prevent starting automatically on boot) ``` sudo systemctl disable ``` ### Viewing Logs (journald) - **View Full Logs:** Show all logs for a service (press `q` to exit). ``` sudo journalctl -u # Example: View all Lighthouse logs sudo journalctl -u w3p_lighthouse-beacon ``` - **Follow Logs (Live):** Watch logs as they are generated (press `Ctrl+C` to exit). ``` sudo journalctl -f -u # Example: Follow Geth logs sudo journalctl -f -u w3p_geth ``` - **View Last N Lines:** Show only the most recent log entries. ``` sudo journalctl -n 50 -u # Shows last 50 lines ``` - **View Logs Since Time:** Show logs since a specific time (e.g., "1 hour ago", "2025-04-24 10:00:00"). ``` sudo journalctl --since "1 hour ago" -u ``` ### System Resource Monitoring - **Interactive Process Viewer:** Shows CPU, Memory usage, tasks. ``` htop ``` - **Disk Usage (Overall):** Show usage for all mounted filesystems. (No `sudo` needed) ``` df -h ``` - **Memory Usage:** Show free and used RAM and Swap. (No `sudo` needed) ``` free -h ``` - **System Uptime & Load:** (No `sudo` needed) ``` uptime ``` ### Node Specific Checks - **Geth Console (Sync Status):** Attach to the Geth console. (No `sudo` needed) ``` geth attach http://localhost:8545 # Inside the console, type: eth.syncing # (Returns 'false' when synced, or sync progress object if syncing) eth.blockNumber # (Shows the latest block number Geth knows) exit # (To leave the console) ``` ### System Updates - **Check for Available Updates:** Refreshes the package list. ``` sudo apt update ``` - **List Upgradable Packages:** See what packages have updates available. (No `sudo` needed) ``` apt list --upgradable ``` - **(Use with Caution) Apply Updates:** Upgrades installed packages. Refer to specific Web3 Pi update guides if available. ``` sudo apt upgrade ``` ## InfluxDB InfluxDB stores device status measurements and serves as the data source for Grafana. The Influx database is fed by the `basic-eth2-node-monitor` application, which collects data from Ethereum clients. It also receives input from the `basic-system-monitor` application, which gathers operating system statistics and serves them as JSON over HTTP. ### Clearing the Database To clear the database, run the following commands: ``` influx USE ethonrpi DROP SERIES FROM /.*/ exit ``` ## Nimbus - **Service name**: `w3p_nimbus-beacon` - **Default directory**: `/mnt/storage/.nimbus/data/shared_mainnet_0` - **Startup script**: `/home/ethereum/clients/nimbus/nimbus.sh` ### Clear saved data ``` sudo rm -r /mnt/storage/.nimbus/data/shared_mainnet_0 ``` ## Geth - **Service name**: `w3p_geth` - **Default directory**: `/mnt/storage/.ethereum` - **Startup script**: `/home/ethereum/clients/geth/geth.sh` ### Clear saved data ``` sudo rm -r /mnt/storage/.ethereum ``` ## Lighthouse - **Service name**: `w3p_lighthouse-beacon` - **Default directory**: `/mnt/storage/.lighthouse` - **Startup script**: `/home/ethereum/clients/lighthouse/lighthouse.sh` ### Clear saved data ``` sudo rm -r /mnt/storage/.lighthouse ``` ## JWT Secret The `jwt.hex` file contains the JWT secret used to enable authenticated communication between the execution client and the consensus client. This file is generated by the installation script. - **Location:** `/home/ethereum/clients/secrets/jwt.hex` ## Storage ### PCIe Generation By default, Web3 Pi uses PCIe Gen 2, which is the officially supported version. However, if you have a PCIe Gen 3 capable device, you can enable it by editing the [config.txt](https://docs.web3pi.io/advanced-setup/config/index.md) file. Benefits of PCIe Gen 3: - **Higher Bandwidth:** PCIe Gen 3 offers double the bandwidth compared to PCIe Gen 2. This means faster data transfer rates, which can be especially beneficial for high-speed storage devices like NVMe SSDs or network cards. - **Improved Performance**: For applications that are bottlenecked by PCIe bandwidth, enabling Gen 3 can significantly improve performance. While Raspberry Pi 5 is designed for PCIe Gen 2, upgrading to Gen 3 can unlock more potential in compatible devices. Warning Enabling PCIe Gen 3 on a Raspberry Pi 5 can cause instability. Only proceed if you know what you're doing and have a compatible device. ## Scripts The Web3 Pi image comes with several useful scripts pre-installed. These can be found in the home directory of the ethereum user at /home/ethereum/scripts. Below is a description of each script and how to execute them: - `sudo ./scripts/shutdown.sh` This script gracefully shuts down the device. It first stops the services, allowing them time to finish their tasks, and then powers off the system. - `sudo ./scripts/reboot.sh` This script gracefully reboots the device. It first stops the services, giving them time to complete their tasks, and then restarts the system. - `sudo ./scripts/formatMe.sh` This script marks the mapped storage as "to be formatted" during the next installation. It’s useful when reinstalling the Web3 Pi image. - `sudo ./scripts/versions.sh` This script checks the versions of the currently installed applications and compares them to the latest available online. It covers applications such as Geth, Nimbus, and Lighthouse. - `sudo ./scripts/update_geth.sh` This script updates the Geth application to the latest available version. It stops the service, installs the new version, and then restarts the service. - `sudo ./scripts/update_nimbus.sh` This script updates the Nimbus application to the latest available version. It stops the service, installs the new version, and then restarts the service. - `sudo ./scripts/check_install.sh` This script checks the installation and configuration of Web3 Pi. It verifies installed packages, active services, disk and swap usage, network connectivity, and other important aspects. The output is formatted and color-coded for better readability. You can also view and execute scripts from the [Cockpit Web3 Pi Script Runner plugin](https://docs.web3pi.io/management/cockpit/web3-pi-script-runner/index.md). ## CCZE Newer version of the Web3 Pi image include CCZE, which enables automatic colorization of logs from applications such as Geth and Nimbus, significantly improving readability. An example how to use CCZE: ``` sudo journalctl -xfu w3p_geth.service | ccze -A sudo journalctl -xfu w3p_nimbus-beacon.service | ccze -A cat /var/log/web3pi.log | ccze ``` # Contact ## Discord You can reach us on our Discord server: [Join Discord](https://discord.gg/aDMw5zeUZ4) ## Contact Form Fill out our contact form to ask a question: [Contact Form](https://www.web3pi.io/contact) ## GitHub For issues, projects, or contributions, visit our GitHub: [GitHub Repository](https://github.com/Web3-Pi/) ## X (Twitter) Follow us or send us a message on X: [Follow us on X](https://x.com/_Web3Pi_) # Troubleshooting ## My node cannot synchronize Synchronization issues can stem from several causes. First, check your internet connection quality - unstable or slow connections significantly delay the synchronization process. Also ensure your NVMe SSD has sufficient capacity (minimum 2TB) and is functioning properly. Overheating can also slow down or interrupt synchronization, so verify that your CPU cooling is working correctly. If your Raspberry Pi 4 is synchronizing too slowly, remember this is normal - the process is much faster on Raspberry Pi 5. You can check synchronization progress in the Web3 Pi panel and verify if the node is actually downloading new blocks. If the problem persists, check: - Whether your firewall is blocking required ports - If the SSD is properly mounted and recognized by the system - If you have the latest version of Web3 Pi software For further assistance, join our Discord channel where you can get help from our community and team. # Downloads ## Web3 Pi Image A comprehensive image packed with tools and references for creating and hosting Ethereum Nodes on Raspberry Pi devices.\ [Ethereum on Raspberry Pi →](https://github.com/Web3-Pi/Ethereum-On-Raspberry-Pi/releases) ## Web3 Pi Imager An intuitive application designed to streamline the process of burning Web3 Pi images effortlessly.\ [Web3 Pi Imager →](https://github.com/Web3-Pi/web3-pi-imager/releases) # Web3 Pi UPS # LTE Connectivity The Web3 Pi UPS accepts an optional plug-in LTE-M module (Cat-M1 / NB-IoT cellular) that gives the UPS its own cellular link — completely independent of your home network and mains power. When the power goes out and your router goes dark, the UPS keeps reporting. The module ships with a pre-installed global IoT SIM and an included data plan — no SIM card, mobile contract, or carrier configuration needed (the SIM also carries the device's identity, so don't swap it). With the module fitted you get: - **Remote monitoring** — telemetry (battery, inputs, host state) uplinked roughly every 30 seconds, wherever the device is. - **Instant alerts** — power-state changes (mains lost/restored) and faults are pushed immediately, not on the next 30 s tick. - **Remote commands** — reboot or shut down the host, power-cycle the output, trigger a beep, and start/stop/restart the Ethereum clients running on the Pi. - **Remote firmware updates** — both the modem module and the UPS controller can be [updated over the air](https://docs.web3pi.io/ups/firmware-update/index.md) from the web panel. - **No network setup** — the module is an outbound-only client, so it works behind carrier-grade NAT. No public IP, port forwarding, or VPN required. ## Backend Modes The module reports to one of three backends — exactly **one active at a time**. **MQTT is the default and recommended mode**: zero configuration, and the full [web panel](https://docs.web3pi.io/ups/connectivity/web-panel/index.md) experience. HTTP and Arkiv are alternatives for specific needs. All three authenticate every message; MQTT and Arkiv are always encrypted, and HTTP mode adds encryption when you use HTTPS. | Mode | Where your data goes | Best for | | -------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | **MQTT** *(default)* | Web3 Pi cloud + [web panel](https://docs.web3pi.io/ups/connectivity/web-panel/index.md) | Most users — zero-config remote monitoring and commands | | **HTTP** | Your own server — [HTTP mode](https://docs.web3pi.io/ups/connectivity/http-mode/index.md) | Self-hosters who want data on their own infrastructure | | **Arkiv** | Web3 Pi's Arkiv-compatible blockchain — [Arkiv mode](https://docs.web3pi.io/ups/connectivity/arkiv-mode/index.md) | Tamper-evident records for special/compliance needs | MQTT and Arkiv devices are fully managed in the [web panel](https://docs.web3pi.io/ups/connectivity/web-panel/index.md). In HTTP mode your own server is the backend — the panel can still list such a device, but its live data and commands go through your server. ## Switching Modes Modes are switched on the device itself, from the [OLED menu](https://docs.web3pi.io/ups/hardware/display-menu/index.md): 1. On the Home screen, hold **LEFT** for 2 seconds to open the menu. 1. Select **Network** (requires the LTE-M module — shows **NO MODEM** otherwise). 1. Select **Mode**, then pick **MQTT**, **ARKIV**, or **HTTP** — `*` marks the active mode. 1. The setting is saved and the LTE-M module reboots into the new mode. The choice persists across reboots and power loss. The module reboot only pauses telemetry for roughly half a minute to two minutes while it reconnects — power to the Pi and battery backup are handled in hardware and are never interrupted. ## Without the Module The LTE-M module adds remote visibility; it is not required for protection. Without it, the UPS still provides the full power path and battery backup, the OLED display, buttons, buzzer alarms, and the local settings menu — plus telemetry, event logging, and graceful shutdown for the connected Pi over the single USB-C cable (see [Host Integration](https://docs.web3pi.io/ups/host-integration/index.md)). # Arkiv Mode Arkiv mode is an alternative telemetry backend for units fitted with the [LTE-M module](https://docs.web3pi.io/ups/connectivity/index.md). Instead of the Web3 Pi cloud, the UPS writes encrypted telemetry to the **Web3 Pi UPS Chain** — a self-hosted, Arkiv-compatible network run by Web3 Pi — creating a tamper-evident record of your device's power history. Ownership is bound to your crypto wallet, and only that wallet can decrypt the data — the panel server never holds the key. MQTT is the recommended default Arkiv mode is a niche option for audit and compliance use cases — it adds wallet management. For day-to-day monitoring, stay in MQTT mode and use the [web panel](https://docs.web3pi.io/ups/connectivity/web-panel/index.md). The device has its **own on-chain wallet** that signs every write, and it is the final authority on ownership: binding to your wallet must be physically confirmed on the UPS itself. ## Enabling Arkiv Mode 1. On the Home screen, hold **LEFT** for 2 s to open the menu, then select **Network** (see [Display & Menu](https://docs.web3pi.io/ups/hardware/display-menu/index.md)). 1. Choose **Mode**, then **ARKIV**. 1. The setting is saved and the LTE-M module reboots. Telemetry drops out for about 30 seconds; power to the Pi and battery backup are unaffected. The mode persists across reboots, and the panel moves the device to its **Arkiv Devices** list automatically. ## Claiming Your Device An unclaimed device in Arkiv mode shows its **ICCID** and a **4-word claim code** on the OLED. The code rotates every 15 minutes, so use the one currently displayed. 1. In the panel, open **Arkiv Devices** → claim page and **Connect Wallet**. 1. Enter the ICCID and the four claim-code words, then click **Sign & submit claim**. Your wallet prompts for two signatures; the panel tops your wallet up with the chain's (valueless) gas token automatically when you connect, so the claim costs you nothing. 1. The device verifies the claim and displays a **4-word owner fingerprint** with a short checksum; the panel shows the identical string. 1. Compare **every word, in order**. If they match, hold **both buttons** on the UPS for 5 seconds to confirm the binding. The binding survives reboots; a factory reset (menu → **Network** → **Reset**) clears it. ## The Device Wallet - **Wallet** → **Address** shows the device's address (alternating with a QR code); **Wallet** → **Balance** shows its current gas balance in **W3P**, the Web3 Pi UPS Chain's anti-spam gas token with no monetary value (firmware before esp32:0.8.11 labelled it "GLM"). The reading no longer depends on telemetry getting through: an unfunded wallet shows `0.000000` with a `no gas` hint, and the screen refreshes within a few seconds of opening it. - During normal operation the panel keeps both your wallet and the device wallet topped up automatically and warns if a balance runs low. One exception: after a **factory reset** the regenerated device wallet cannot announce itself until it holds gas, so its first top-up is manual — send a little W3P to the address shown under **Wallet** → **Address** (or ask Web3 Pi), then telemetry resumes on its own. - **Wallet** → **Regen** generates a new device wallet, invalidating the existing identity and claim — only use it if you intend to re-claim the device. Right after a Regen or factory reset, telemetry may pause until the panel learns the new wallet address and funds it. ## What Works and Current Limitations | Works today | Limitations | | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Encrypted telemetry every 30 s; decrypt in the panel via **Unlock telemetry** (one signature per session) | The chain is self-hosted by Web3 Pi (single RPC gateway) — tamper-evident, but availability depends on Web3 Pi infrastructure; it is not a public blockchain | | Remote commands from the panel — same command set as MQTT, one wallet signature each | A command can linger as *submitted on-chain* instead of *confirmed by device* if the device cannot post its acknowledgement (e.g. right after a factory reset, before its wallet is re-funded) | | [Remote firmware updates](https://docs.web3pi.io/ups/firmware-update/index.md) — same as MQTT mode, owner-signed like every command | Telemetry may pause briefly after a wallet **Regen** or factory reset, until the panel learns and funds the new device wallet | | Owner-only privacy — nobody without your wallet can read the data | You need the owner wallet connected to view any telemetry | Prefer running against your own infrastructure instead? See [HTTP mode](https://docs.web3pi.io/ups/connectivity/http-mode/index.md). # Self-Hosted HTTP Mode HTTP mode is the [backend mode](https://docs.web3pi.io/ups/connectivity/index.md) for operators who want UPS data on **their own server** — no cloud account, no third-party services. The UPS POSTs signed telemetry JSON to an endpoint you host, and your server queues commands in return. ## How It Works The UPS is an **outbound-only HTTP client**, so it works behind cellular carrier NAT — no public IP, port forwarding, or VPN needed. Every ~30 s it POSTs telemetry to `{base}/api/v1/devices/{device_id}/telemetry` (`{device_id}` defaults to the SIM's ICCID); commands ride back **in the POST response**, so command latency is up to ~30 s. **Both directions are HMAC-SHA256 signed**, so nothing can be forged even over plain `http://` — TLS is optional and adds confidentiality only. ``` UPS ── POST /api/v1/devices//telemetry ──────────────▶ your server {"ts":1780047458,"fw_ver":"…","uptime_s":137, "power":{…},"host":{…},"net":{…},"acks":[]} UPS ◀───────────────────────────── 200 OK (signed) ── your server {"commands":[{"id":"c-0043","cmd":"ui.beep","args":{}}]} ~30 s later, next POST: {"ts":…, …, "acks":["c-0043"]} ``` An id in `acks` confirms that the UPS took the command onto its internal bus, **not** that it was executed — see [Available Commands](#available-commands) for how to tell. This page is a quick-start — see the full [HTTP mode specification](https://github.com/Web3-Pi/Web3-Pi-UPS/blob/main/docs/http-control-mode.md) for signature headers, body schema, and replay protection. ## What You Need | Requirement | Notes | | ------------------------------------- | --------------------------------------------------------------------------------------------------- | | UPS with LTE-M module | HTTP mode runs over the cellular link | | A small Linux server with a public IP | Any VPS or always-on host works — [Step 1](#step-1-get-a-server) walks you through a 5-minute setup | | The device's **HTTP key** | Read it off the OLED (below) — this is the shared HMAC secret | | Brief access to the Raspberry Pi | To send the endpoint URL to the UPS over the USB serial link | ## The HTTP Key The device generates its own HTTP-mode secret and shows it on the OLED: open the menu (hold **LEFT** for 2 s on the Home screen), then **Network** → **HTTP Key**. It is a 16-character code (Crockford base32, ~80 bits); case and separators don't matter when typing it in. **New key** re-rolls it (after a confirmation screen) — the old key stops working at once, no reboot needed. The key survives reboots and mode switches; only a factory reset clears it. See [Display & Menu](https://docs.web3pi.io/ups/hardware/display-menu/index.md). ## Setup Four steps in three places: **your server** (steps 1–2), the **Raspberry Pi** (step 3), and the **UPS OLED menu** (step 4). ### Step 1 — Get a Server Any always-on Linux machine the UPS can reach over the internet works: a VPS you already rent, or a home server with a public IP. If you have one, skip to [Step 2](#step-2-start-the-server). If you don't, a minimal VPS is set up in about five minutes and the smallest tier is more than enough — the reference server is a single zero-dependency Python script. For example, on [DigitalOcean](https://www.digitalocean.com): 1. Sign up, then choose **Create → Droplets**. 1. Pick a region near you, the **Ubuntu 24.04 (LTS)** image, and the cheapest plan (from a few dollars a month, billed per second up to the monthly cap — destroy the droplet anytime and pay only for the time it existed). 1. Add your SSH key (or choose a root password) and click **Create Droplet**. After about a minute, note the droplet's **public IPv4 address** — that address goes into the device URL in step 3. Any other provider (Hetzner, AWS Lightsail, OVH, …) works the same way — just make sure the plan includes a **public IPv4 address** (the very cheapest tiers at some providers are IPv6-only, which the UPS's cellular link cannot reach). Firewall — the port must be open The UPS connects **to your server** on the port you choose below (**8080** in the examples). A fresh DigitalOcean droplet accepts it out of the box, but: - if the host firewall is active (`sudo ufw status` says `active`), allow the port: `sudo ufw allow 8080/tcp` - if your provider has a cloud firewall / security group attached to the server (DigitalOcean *Cloud Firewalls*, AWS *security groups*), add an inbound rule for TCP 8080 there too. ### Step 2 — Start the Server First read your two values off the hardware: - **HTTP key** — on the UPS OLED: menu → **Network** → **HTTP Key** ([above](#the-http-key)), e.g. `ABCD EFGH JKMN PQRS`. - **ICCID** — the SIM's serial number, printed on the SIM card/tray. This is the device ID. Then SSH into your server and download the reference server: ``` curl -fsSLO https://raw.githubusercontent.com/Web3-Pi/Web3-Pi-UPS/main/examples/http-control-server/server.py ``` It comes from [`examples/http-control-server`](https://github.com/Web3-Pi/Web3-Pi-UPS/tree/main/examples/http-control-server) in the public UPS repository — a single script with **no dependencies** beyond Python 3, which Ubuntu ships with. Now start it, substituting your HTTP key (quotes matter, spaces inside don't) and ICCID: ``` python3 server.py --secret "" --device-id --port 8080 ``` You should see: ``` listening on http://0.0.0.0:8080 endpoint POST /api/v1/devices//telemetry device_id type 'help' for the command menu; Ctrl-C / Ctrl-D to quit ``` Keep it running The server runs in the foreground — it prints telemetry and takes commands from your keyboard — so it stops when your SSH session drops. Run it inside `tmux` (`sudo apt install -y tmux`, then `tmux`; detach with **Ctrl-B** then **D**, `tmux attach` brings it back) or `screen` (detach with **Ctrl-A** then **D**, `screen -r` brings it back). If your server stops answering while the internet is reachable (server down, wrong URL, wrong key), the UPS keeps its cellular link up and simply retries every 30 s; after about 30 minutes without a successful POST it shows **! MODEM / NO UPLINK / no uplink** on the OLED and beeps. This is harmless — power to the Pi is unaffected — and it clears itself as soon as the server answers again. Only when the internet itself is unreachable (no answer from the server *and* from public DNS for about 6–7 minutes after the last successful POST) does the UPS re-establish the cellular link. ### Step 3 — Point the UPS at Your Server The endpoint URL is sent to the UPS over the USB serial link from the Raspberry Pi it powers — it is stored on the device, no re-flash needed. On the **Raspberry Pi**: ``` curl -fsSLO https://raw.githubusercontent.com/Web3-Pi/Web3-Pi-UPS/main/examples/http-control-server/send_config.py sudo apt install -y python3-serial sudo systemctl stop w3p-ups # frees the UPS serial port python3 send_config.py --url http://:8080 sudo systemctl start w3p-ups ``` The serial port is auto-detected, and success looks like: ``` auto-detected port: /dev/ttyACM0 (Web3_Pi_UPS …) sent net.config HTTP_URL = "http://:8080" (… bytes) to /dev/ttyACM0 device confirmed net.config: OK ``` `no confirmation seen …` instead of that last line usually still means the URL was applied (the reply can get lost amid telemetry) — carry on and confirm in [Verify](#verify) below. A permission error opening the port means your user isn't in the `dialout` group — re-run with `sudo`. And if the [host service](https://docs.web3pi.io/ups/host-integration/index.md) isn't installed, the `systemctl` lines report `Unit w3p-ups.service not loaded` — that's fine, the port is already free; skip them. The URL is stored until factory reset. Optional, as a separate run (the two flags can't be combined): `send_config.py --device-id ` overrides the ICCID default; an empty string (`--url ""` / `--device-id ""`) clears the respective setting. ### Step 4 — Switch the UPS to HTTP Mode On the UPS OLED: menu → **Network** → **Mode** → **HTTP**. The setting is saved and the LTE-M module reboots (~30 s telemetry gap; power to the Pi is unaffected). ### Verify Within ~30 s of the mode switch, the first telemetry POST shows up in the server terminal. Then test the command path end-to-end: type `beep` at the server prompt — the UPS picks it up on its next POST and sounds the buzzer (up to ~30 s later). If nothing arrives after a couple of minutes, check in order: 1. **Cellular link** — was the device reporting before the switch (e.g. online in the [web panel](https://docs.web3pi.io/ups/connectivity/web-panel/index.md) in MQTT mode)? If it has never been online in any mode, the problem is cellular coverage, not your server. 1. **Server** — still running, and the port open (firewall — [Step 1](#step-1-get-a-server)). 1. **URL** sent in step 3 — right IP, right port, `http://` prefix, **no trailing slash**, and the **final URL only** — the UPS does not follow redirects (firmware esp32:0.8.10 or newer: a `3xx` is logged and nothing is applied; older firmware followed redirects instead). 1. **Key and device ID** — a wrong `--secret` is logged by the server as `! rejected: bad signature`; a wrong `--device-id` is **silent** (the server answers 404 without printing anything), so re-check the ICCID digit-for-digit. No hardware yet? `test_client.py` from the same [examples directory](https://github.com/Web3-Pi/Web3-Pi-UPS/tree/main/examples/http-control-server) simulates a correctly-signed device POST, so you can smoke-test the server before touching the UPS. Adding TLS Put any reverse proxy (Caddy, nginx) with a certificate in front of the server and re-run `send_config.py` with the `https://` URL. Use a publicly-trusted certificate (Caddy obtains a Let's Encrypt one automatically — this needs a domain name); self-signed certificates are rejected by the device. Data usage on the bundled SIM The SIM shipped with the UPS is a prepaid 1NCE pool of **500 MB or 10 years, whichever comes first** — a lifetime allowance, not a monthly plan. Measured on the bench: plain `http://` at the default 30 s poll uses ≈ 1.6 KB per poll ≈ **4.7 MB/day**, so the pool lasts ≈ **107 days**. `https://` costs several times more — every poll opens a fresh TLS connection with a full handshake — estimated at ≈ 16–26 MB/day, i.e. **3–4 weeks** per pool. Both directions are HMAC-signed, so plain `http://` is already safe against forgery: prefer it on the bundled SIM, and use `https://` with your own SIM or data plan (top-ups of the bundled SIM are not self-service yet). The poll period is fixed in the current firmware. Measurement method and how to read your own usage from `net.bytes_tx` / `net.bytes_rx`: [spec §9 Data budget](https://github.com/Web3-Pi/Web3-Pi-UPS/blob/main/docs/http-control-mode.md#9-data-budget). ## Available Commands These five commands are the complete set the HTTP backend executes (same semantics as the [web panel](https://docs.web3pi.io/ups/connectivity/web-panel/index.md) commands; anything else is refused and reported back in the next POST's `rejected` list — firmware esp32:0.8.10 or newer; older firmware ignores unknown commands silently): | Command | Effect | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ui.beep` | Sound the buzzer — a quick end-to-end test | | `ui.display_msg` | Show a short text message on the OLED (40 characters visible; shown as a plain notice on rp2040 1.2.2 or newer — older RP2040 firmware displayed it as a MODEM alarm) | | `host.shutdown` | Graceful Raspberry Pi shutdown (the delay argument is currently ignored — immediate) | | `host.reset` | Reboot the Raspberry Pi (the delay argument is currently ignored — immediate) | | `power.cycle` | Power-cycle the **OUT** port (fixed 1.5 s off time in the current CH32X firmware) | What an ack means An id in `acks` means the UPS **accepted the command and handed it to its internal bus** (to the display controller, the Raspberry Pi host service or the power controller) — it does not confirm that the command was executed. Execution is visible out-of-band: `ui.beep` is audible; `ui.display_msg` appears on the OLED; after `host.shutdown` the `host` object drops out of telemetry within about two minutes; after `host.reset` `host.uptime_s` restarts from a small value in a later report (the `host` object may or may not drop out in between — a Pi that is back within 90 s never disappears); `power.cycle` shows as the `VBUS_OUT_EN` bit of `power.flags` clearing / `vbus_out_mv` dipping, but a 1.5 s dip is usually missed by the 30 s poll — the Pi rebooting (`host.uptime_s` restarting) is the reliable sign. Details: [Verifying that a command took effect](https://github.com/Web3-Pi/Web3-Pi-UPS/blob/main/docs/http-control-mode.md#verifying-that-a-command-took-effect) in the specification. Keep responses small The UPS applies **at most 8 commands per poll** and drops a response body larger than **2047 bytes** as a whole — nothing in it is applied, and the next POST tells the server so in a `resp_dropped` field. Commands past the eighth are neither applied nor acked, so a longer queue simply drains 8 per poll. This is firmware esp32:0.8.10 or newer (check `fw_ver` in the POST); older firmware has no such guard — an over-size response is silently dropped and never acked, so keep responses small on every version. The reference server enforces both limits by default (`--max-commands 8`, response cap 2047 B); if you write your own server, see [Receiver limits (device side)](https://github.com/Web3-Pi/Web3-Pi-UPS/blob/main/docs/http-control-mode.md#receiver-limits-device-side) in the specification. No firmware updates in HTTP mode Remote [firmware updates](https://docs.web3pi.io/ups/firmware-update/index.md) are delivered over MQTT (or Arkiv) only. To update a device parked in HTTP mode, switch it back to MQTT from the OLED menu for the update, then switch back — or flash it locally over USB with the [Workbench](https://docs.web3pi.io/ups/firmware-update/#local-updates-over-usb-workbench). ## Security Notes - **Guard the HTTP key.** If it leaks, re-roll it on the OLED (**HTTP Key** → **New key**) and update your server. - **Keep the server clock NTP-synced.** The device timestamps requests from network time; a drifting server clock rejects valid requests as stale. - The reference server is an **example, not hardened infrastructure**: no operator authentication, persistence, or rate limiting. Web panel in HTTP mode HTTP-mode devices still appear on the [web panel](https://docs.web3pi.io/ups/connectivity/web-panel/index.md)'s HTTP page, but your server is the backend — the panel cannot configure the endpoint. # Web Panel [panel.web3pi.io](https://panel.web3pi.io) is the cloud dashboard for your Web3 Pi UPS: claim your unit, watch its telemetry and events, and send remote commands — even when the power or your home network is down. It requires the [LTE-M module](https://docs.web3pi.io/ups/connectivity/index.md); out of the box the device reports in MQTT mode, which needs no configuration on the device at all. ## Create an Account 1. Open `https://panel.web3pi.io`. You are redirected to the Web3 Pi sign-in page at `auth.web3pi.io`. 1. Click **Need an account? Sign up.** and register with your email address. 1. Confirm the verification link sent from `noreply@web3pi.io` — the account is active only after verification. 1. Sign in. Optional two-factor authentication (authenticator apps, passkeys/security keys, backup codes) is available under your avatar menu → **Account settings**. After signing in you land on the **Overview** page; your devices live under **Web3 Pi UPS → MQTT Devices**: ## Claim Your Device A device only shows up in your panel after you claim it. 1. Go to **Web3 Pi UPS → MQTT Devices** and click **Claim MQTT device**. 1. Enter the **ICCID** (19–20 digits) and the **claim token** (format `XXXXX-XXXXX`) — both are on the setup card included with your UPS. 1. Confirm — the device appears in your list and its telemetry lands within about 30 seconds. Arkiv devices are claimed under **Web3 Pi UPS → Arkiv Devices** with a crypto wallet and the **4-word claim code** from the device OLED, and the binding is confirmed on the UPS itself. Follow the walkthrough in [Arkiv mode](https://docs.web3pi.io/ups/connectivity/arkiv-mode/#claiming-your-device). One device, one owner A device belongs to exactly one account. For MQTT devices the claim token stays valid for the device's whole life: to sell or hand a unit over, open its **Settings** tab and use **Release device** — the new owner claims it with the same ICCID and token. Arkiv devices are bound to a wallet instead; releasing in the panel does not clear that binding — a factory reset on the device does (see [Arkiv mode](https://docs.web3pi.io/ups/connectivity/arkiv-mode/index.md)). ## What You See The sidebar lists your units by backend mode (**MQTT Devices**, **Arkiv Devices**), plus fleet-wide **Events** and **Command History**. The device list shows each unit's name, online state (online = reported within the last 3 minutes), battery and input voltage, last-seen time, LTE signal strength, and remaining SIM data. Click a device to open its detail pane with **Status**, **Commands**, **Events**, and **Settings** tabs. The **Status** tab updates live: - **UPS** — battery charge, input/output voltage, temperature, mains present, fault state. - **System** — host stats from the [companion service](https://docs.web3pi.io/ups/host-integration/index.md): CPU temperature, RAM, disk, load, uptime. - **ETH Clients** — execution / consensus / validator shown as running, stopped, or failed. This is the service state on the Pi, not chain sync status. - **LTE Modem** — signal quality and RSSI, link state, RSRP/RSRQ, and data counters. A red **UPS link down** banner appears if the LTE module hasn't received valid UPS data for over 90 s — the power tiles go blank and the suggested remedy is **Commands → Restart ESP32**. Devices report roughly every 30 seconds over LTE, but power-loss and fault events are pushed immediately — an outage shows up in the panel within seconds. ## Remote Commands The **Commands** tab targets the selected device: | Group | Commands | Notes | | ---------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | UPS output | Power on · Power off · Cycle output | Cycle cuts output for 1.5 s — hard-reboots the Pi | | Raspberry Pi | Reboot OS · Shutdown OS | Graceful shutdown; the UPS keeps supplying power | | Diagnostics | Request status · Beep / self-test · Restart ESP32 | Restart ESP32 restarts the LTE module only — telemetry pauses a minute or two; UPS output and the Pi keep running | | Ethereum clients | Start · Restart · Stop per client | Acts on the whitelisted services on the Pi | | Firmware update | Send an over-the-air update to the modem module (ESP32) or the UPS controller (RP2040) | Full walkthrough: [Firmware Updates](https://docs.web3pi.io/ups/firmware-update/index.md) | Destructive commands ask for confirmation. On MQTT devices every command is tracked from *accepted* to *confirmed by device* (or *failed* / *timed out*). On Arkiv devices each command requires one wallet signature and may show as *submitted on-chain* rather than confirmed — see [Arkiv mode](https://docs.web3pi.io/ups/connectivity/arkiv-mode/index.md). ## Events and Command History **Events** collects power and host alerts from your whole fleet — mains lost/restored, battery low/full, faults, imminent host shutdown, low disk, backend-mode changes, and firmware-update progress — filterable by device, severity, source, backend, and date. **Command History** logs every issued command with its status, latency, and the account that sent it. ## Settings Per-device settings live in the device's **Settings** tab: rename the unit, review backend details (full ICCID, IMEI, remaining data, hardware revision, ESP32 firmware version, claim date), and release it in the **Danger zone** — release asks you to type the device's exact name to confirm. Account-level settings (password, two-factor, active sessions) are managed in your Web3 Pi account via the avatar menu → **Account settings**. Running your own backend? Devices switched to [HTTP mode](https://docs.web3pi.io/ups/connectivity/http-mode/index.md) report to your own server instead and drop out of the MQTT Devices list — the sidebar has no HTTP entry; their list lives only at `panel.web3pi.io/ups/http`, and live telemetry and commands go through your server. # Hardware Tour The Web3 Pi UPS is a compact, silent DC UPS that sits between your charger and the Raspberry Pi 5. Everything you touch day to day — display, buttons, battery — is on the top and front of the unit; power inputs are on the rear. ## Front and Top *Front view: OLED with its two red buttons, the* *OUT* *port below the Web3 Pi logo, the battery on its top rail, and the red* *PUSH* *latch on the side.* - **OLED display** — a small monochrome screen behind a smoked window, showing charge level, power mode, and input/output voltages. See [Display & Menu](https://docs.web3pi.io/ups/hardware/display-menu/index.md) for every screen. - **Two buttons** — the round red buttons flanking the display. Short presses cycle through the status screens; holding the **LEFT** button for 2 s on the Home screen opens the settings menu ([details](https://docs.web3pi.io/ups/hardware/display-menu/index.md)). - **USB-C OUT** — on the front face, labeled **OUT**. A single cable to the Pi carries both power and USB data. - **Battery latch** — the red **PUSH** tab on the side edge. Press it and slide the battery off its rail; the battery is [hot-swappable](https://docs.web3pi.io/ups/hardware/battery/index.md) while the UPS runs on external power. ## Rear *Rear inputs: USB-C* *IN* *with the DC barrel jack next to it.* - **USB-C IN** — USB-C Power Delivery input, 9–20 V auto-negotiated. The primary way to power the UPS, e.g. from a 45 W USB-C charger. - **DC jack** — alternative DC input, 12–20 V (5.5/2.5 mm barrel), for desktop supplies or other DC sources. Both inputs can be connected at the same time: the UPS draws from whichever presents the higher voltage, and if that source fails it switches to the other seamlessly. As long as at least one cable input is powered, you can also [hot-swap the battery](https://docs.web3pi.io/ups/hardware/battery/index.md) without interrupting the Pi. The output stays up while **any one** of the three power sources — USB-C **IN**, DC jack, or battery — is available; see [Power & Failover](https://docs.web3pi.io/ups/power/index.md). ## Ports at a Glance | Port | Location | Purpose | | ------------- | -------- | --------------------------------------------------------------------------------------------------------- | | USB-C **OUT** | Front | Output to the Pi 5: 5 V / 5 A power plus USB data (telemetry, safe shutdown) on one cable | | USB-C **IN** | Rear | USB-C PD input, 9–20 V (auto-negotiated); 26 W minimum, 45–65 W recommended | | DC jack | Rear | Alternative DC input, 12–20 V (5.5/2.5 mm barrel) | | Battery rail | Top | Sony NP-F battery — user-replaceable, see [Battery](https://docs.web3pi.io/ups/hardware/battery/index.md) | OUT is output-only Never feed power into the **OUT** port. Connect chargers only to **IN** or the DC jack. ## Buzzer An internal buzzer gives audible feedback: button clicks, a short startup melody, a power-loss alarm when the unit switches to battery, low/critical battery warnings, and a bad-power-supply alert (rapid beeping — see [Troubleshooting](https://docs.web3pi.io/ups/troubleshooting/index.md)). All sounds — alarms included — can be muted from the [settings menu](https://docs.web3pi.io/ups/hardware/display-menu/index.md). ## Status LEDs There are no external status LEDs. The OLED display and buzzer provide all user feedback. ## Inside The enclosure houses two boards: the main power board and the display/button panel. An internal M.2 slot accepts the optional LTE-M module for out-of-band [connectivity](https://docs.web3pi.io/ups/connectivity/index.md) — no disassembly is needed for normal use. # Battery The Web3 Pi UPS uses Sony NP-F series batteries — 7.2 V Li-Ion camera packs that are cheap, widely available, and user-replaceable. The pack slides onto a standard NP-F rail on top of the unit. ## Supported Models | Model | Capacity | Runtime | | ------- | ------------------ | ----------------------- | | NP-F570 | 2600 mAh (18.7 Wh) | Shortest — most compact | | NP-F770 | 5200 mAh (38.5 Wh) | Mid-range | | NP-F970 | 9600 mAh (71 Wh) | Longest | Runtime depends on your Raspberry Pi's workload; other NP-F-compatible packs also fit. Capacities above are for the recommended **Newell** packs — see [Specifications](https://docs.web3pi.io/ups/reference/specifications/#battery) for links. Use packs with internal protection The UPS relies on the battery's own built-in protection circuit (BMS) for cell-level and deep-discharge protection. Use quality NP-F packs that include one — virtually all genuine and reputable third-party packs do. ## Inserting and Removing - **Insert**: set the battery on the top rail offset by about half its length — NP-F packs engage the rail from roughly their midpoint — then slide it on until the red **PUSH** latch clicks. - **Remove**: press the red **PUSH** latch on the side edge and slide the battery off the rail. ## Hot-Swap The battery can be swapped **while external power is present** (USB-C **IN** or the barrel jack) — the output to the Pi stays up the whole time. Check before you pull Before swapping, confirm the unit is not running on battery: the Home screen mode should read anything other than `DSC` (discharging). Removing the battery while it is the only power source cuts power to the Pi. ## Charging Charging is fully automatic — there is nothing to configure: - Whenever external power is present and the pack is below full, the UPS charges it. - Charging is deliberately gentle: a modest charge current and a ~8.1 V "gentle full" target (below the pack's maximum) extend battery lifespan. - When the pack is full, charging stops: the mode label shows `FUL`, then `IDL`. On external power the Pi is always fed from the input, so a full pack simply rests — and takes over seamlessly if the input fails. - When power returns after an outage, charging resumes on its own. ## Reading Charge State on the OLED The **Home** screen shows a battery icon (fill level = charge, scrolling bars while charging, blinking below 10 % on battery), the charge percentage, and a mode label. The **BATTERY** [detail screen](https://docs.web3pi.io/ups/hardware/display-menu/#detail-screens) adds battery voltage and charge current. | Label | Meaning | | ----- | ----------------------------------- | | `DSC` | Discharging — running on battery | | `PRE` | Pre-charge (deeply discharged pack) | | `CHG` | Charging | | `FUL` | Full | | `IDL` | On external power, not charging | On battery, the buzzer beeps once every 30 s below 20 % charge and twice every 5 s below 10 % (unless the buzzer is muted via menu → **Sound** — see [Display & Menu](https://docs.web3pi.io/ups/hardware/display-menu/index.md)); the companion service can shut the Pi down safely before the battery runs out — see [Host Integration](https://docs.web3pi.io/ups/host-integration/index.md). Note The charge percentage is estimated from battery voltage and can read optimistically while charging. See [Display & Menu](https://docs.web3pi.io/ups/hardware/display-menu/index.md) for the full screen reference and [Power](https://docs.web3pi.io/ups/power/index.md) for failover and charging behavior in detail. # Display & Menu The UPS has a 64 × 32 monochrome OLED and two red buttons, one on each side of the display. On power-up it plays a short melody and shows a splash screen for a few seconds while readings stabilize, then lands on the **Home** screen. ## Status Screens The **Home** screen is the main display: a battery icon (fill = charge level, animates while charging), charge %, mode label, battery voltage, plus input and output voltage. Mode labels: `DSC` discharging (on battery) · `PRE` pre-charge · `CHG` charging · `FUL` full · `IDL` on external power, not charging. ### Detail Screens Four detail screens sit next to **Home**, cycled with short button presses; a small position strip in the bottom-right corner shows where you are, and the display returns to **Home** automatically after 20 s without a button press. | Screen | Shows | | ----------- | ----------------------------------------------------------------------------------------------------- | | **INPUT** | Input voltage, negotiated USB-C PD contract and its wattage, active source (**USB-C** / barrel / off) | | **OUTPUT** | Measured output voltage, the PD contract offered to the Pi, current limit | | **BATTERY** | Battery voltage and charge %, mode label, charge current | | **SYSTEM** | Uptime, board and charger temperatures, fault code | Warning screens Three warnings can override the status screens: - **BAD PSU** — the input supply is present but out of range: a flashing warning with alarm beeps until you connect an adequate charger. - **MODEM** — the LTE-M module cannot get online (shows a short reason such as `SIM ERROR` or `NO NETWORK`, with a reminder beep every 10 s). Any button press dismisses it; it clears itself once the module reconnects. See [Troubleshooting](https://docs.web3pi.io/ups/troubleshooting/index.md). - **NO UPS / pwr data lost** — the display controller lost internal telemetry for more than ~5 s (reminder beep every 30 s). The UPS usually still powers the Pi, and the screen normally self-recovers within a minute. ## Buttons | Context | **LEFT** | **RIGHT** | | -------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------- | | **Home** / detail screens | Short press: previous [detail screen](#detail-screens). Hold 2 s on **Home**: open the menu | Short press: next [detail screen](#detail-screens) | | Menu | Move cursor down (wraps) / toggle the highlighted option | Select / activate | | **MODEM** warning | Any button: dismiss the warning | | | Confirmation prompts (device claiming) | Hold **both** buttons for the on-screen countdown to confirm; release to abort | | Every press gives a short click from the buzzer (unless sound is off). ## Local Menu Hold **LEFT** for 2 s on the **Home** screen. Navigate with **LEFT** (down) and **RIGHT** (select); the menu closes itself after 60 s of inactivity, saving any pending change. | Entry | What it does | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Bright** | Display brightness, 6 levels with live preview — **RIGHT** cycles, **LEFT** saves and returns | | **Sound** | Toggles the buzzer **ON**/**OFF** with **RIGHT**, saved immediately | | **Info** | Read-only: uptime and board/charger temperatures; any button returns | | **Output** | Shows the output state; **Turn OFF** asks for confirmation (`CUT PWR TO PI?`) before cutting power to the Pi, **Turn ON** is immediate | | **Network** | Opens the connectivity menu of the optional LTE-M module — a shortcut to the detail screens (**Debug**), backend mode selection (**Mode**), **HTTP Key**, factory reset (**Reset**), device **Wallet**, and **Back**. See [Connectivity](https://docs.web3pi.io/ups/connectivity/index.md). Without the module fitted it shows a brief **NO MODEM** notice | | **Exit** | Closes the menu | **Bright** and **Sound** persist across power cycles and battery swaps. A factory reset (in the **Network** menu) restores both to defaults. Sound OFF mutes everything Turning **Sound** off silences all audio, including the power-loss and low-battery alarms — not just button clicks. # Wire Protocol (WUPS) WUPS is the open binary protocol (version 1) that the Web3 Pi UPS speaks with its host over the same USB-C cable that powers the Pi. It is what the companion service uses for telemetry, event logging, graceful shutdown, and whitelisted service restarts — and what you would implement to integrate the UPS with your own software. This is an overview, not the spec This page tells you what the protocol looks like and what it can do. The authoritative, byte-exact specification lives in the source code — see [Authoritative Spec](#authoritative-spec). ## Transport The UPS enumerates as a USB CDC serial device (`/dev/ttyACM*` on Linux) with the USB product string `Web3_Pi_UPS`. The reference service auto-detects the port by that string and opens it at 115200 baud. See [Host Integration](https://docs.web3pi.io/ups/host-integration/index.md) for installing the ready-made service instead of talking to the port yourself. ## Framing Frames are UBX-style binary (same Fletcher-8 checksum algorithm as u-blox UBX). All multi-byte fields are little-endian. ``` +------+------+-----+-----+-------+----+-------+-----+-------+-------+ ~~~~~~~~~ +------+------+------+------+ | 0xAA | 0x55 | DST | SRC | CLASS | OP | FLAGS | SEQ | LEN_L | LEN_H | payload | CK_A | CK_B | 0x55 | 0xAA | +------+------+-----+-----+-------+----+-------+-----+-------+-------+ ~~~~~~~~~ +------+------+------+------+ sync bytes addressing message id flags seq LEN, LE u16 0–240 bytes Fletcher-8 end marker ``` - Checksum covers `DST` through the last payload byte (sync bytes and end marker excluded). - Total frame size = 14 + `LEN` bytes; maximum 254 bytes. - `FLAGS` encodes the messaging model: **REQ** (expects a response), **RESP** (echoes the request's `SEQ` for correlation), **EVENT** (unsolicited push). Requests time out after 1 s with up to 3 retries; there is no retransmission layer beyond that. - `DST`/`SRC` address the nodes in the system (host = `0x01`, `0xFF` = broadcast); as an integrator you only ever see the USB side. ## Message Groups | Class | Group | What It Carries | | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0x01` | System | Ping, boot hello (protocol version + capabilities), log messages, backend-mode change notifications, remote node reset | | `0x02` | Power | Telemetry pushed at 1 Hz (input/output PD contracts, voltages, currents, battery charge, temperatures, faults) plus output-rail control and power events: mains lost/restored, charge low/full, fault | | `0x03` | Network | LTE-M modem status (signal, IP, data counters), opaque cloud uplink/downlink, time sync, runtime configuration of [HTTP mode](https://docs.web3pi.io/ups/connectivity/http-mode/index.md) — no reflash needed — and [firmware updates](https://docs.web3pi.io/ups/firmware-update/index.md): OTA download over LTE plus a chunked image transfer used for remote RP2040 updates and browser-based flashing | | `0x04` | Host | Host metrics for the OLED (CPU temperature, load, disk, Ethereum client states), graceful **shutdown**/**reboot** requests with reason and delay, whitelist-enforced service start/stop/restart | | `0x05` | UI | Button events, display and buzzer control, on-device trust confirmations | ## Versioning The global protocol version (currently **1**) is announced in the hello message. Independently, payloads conventionally carry their own version as their **first byte** — for example, the power telemetry payload is currently at payload version 2 (a few control payloads, such as transfer chunks and 1-byte result responses, do not). Parsers should dispatch on that byte, so payloads can evolve without breaking the framing or other messages. ## Authoritative Spec The full specification ships with the open firmware source: - [`common/protocol.h`](https://github.com/Web3-Pi/Web3-Pi-UPS/blob/main/common/protocol.h) — the canonical, machine-readable spec (frame constants, all classes/ops, payload structs) - [`common/protocol_desc.md`](https://github.com/Web3-Pi/Web3-Pi-UPS/blob/main/common/protocol_desc.md) — human-readable companion with worked examples Where the two disagree, `protocol.h` wins. A reference host implementation in Rust is available at [Web3-Pi-UPS-Service](https://github.com/Web3-Pi/Web3-Pi-UPS-Service), and a minimal zero-dependency Python integration example lives in the firmware repo under `examples/http-control-server/`. # Specifications Reference data for the Web3 Pi UPS — a true DC UPS (no AC inverter) for the Raspberry Pi 5 and other USB-C PD devices. For behavior details see [Power & Failover](https://docs.web3pi.io/ups/power/index.md); for the data link see [Host Integration](https://docs.web3pi.io/ups/host-integration/index.md) and the [Protocol Reference](https://docs.web3pi.io/ups/reference/protocol/index.md). ## Power Output | Parameter | Value | | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | | Output port | USB-C **OUT** — power + data over a single cable | | Native Raspberry Pi 5 profile | 5 V / 5 A (27 W peak) — the UPS identifies itself as a 27 W supply, unlocking the Pi 5's full power envelope | | USB-C PD output profiles | 5 V / 5 A · 9 V / 3 A · 12 V / 2.25 A · 15 V / 1.8 A, auto-negotiated | | Designed workload | A Raspberry Pi 5 running a Web3 Pi node/validator — typically well under 15 W, sustained indefinitely | | Cable requirement | E-marked USB-C cable recommended for 5 A operation — the UPS cannot detect an under-rated cable | Peak vs. sustained load The 27 W profile covers the Pi 5's power peaks. The UPS is a compact, fanless device built around a node/validator workload, which it powers around the clock; it is not meant as a general-purpose charger, and sustained loads above ~20 W (e.g. charging a laptop) can build up heat, especially in warm surroundings. OUT is output only Never feed power into the **OUT** port. ## Power Input | Parameter | Value | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | USB-C PD input (**IN**) | 9–20 V, auto-negotiated (15 V preferred), 26 W minimum | | DC barrel jack | 12–20 V DC, 5.5/2.5 mm connector | | Recommended source | **45 W or more** — a supply rated at least 45 W is required to deliver the full 27 W (5 V / 5 A) output; extra headroom also charges the battery under full load | | Source selection | Automatic — with both external inputs connected, the higher voltage supplies the load | | Power sources | 3 (USB-C PD, DC jack, battery) with seamless switching; output is maintained while any single source is available | | Power path | Active — battery is bypassed when full and external power is present (less battery wear); instant failover to battery | ## Battery | Parameter | Value | | ------------ | ----------------------------------------------------------------------------------------------------- | | Battery type | Sony NP-F series, 2S Li-Ion, 7.2 V nominal | | Replaceable | Yes — user-replaceable, hot-swappable under external power | | Charging | Automatic when external power is present; gentle-full target ≈ 8.1 V, modest charge current by design | | Protection | Pack's internal protection circuit required — use quality NP-F packs | Compatible battery options — runtime depends on your Raspberry Pi's workload. Use batteries from reputable manufacturers with a built-in protection circuit (BMS); we recommend **Newell** packs: | Battery | Capacity | Runtime | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | --------- | | [Newell NP-F570](https://shop.newell.pro/pl/akumulatory-do-aparatow-fotograficznych-i-kamer/842-akumulator-newell-zamiennik-np-f570-do-sony-5901891109528.html) | 2600 mAh (18.7 Wh) | Shortest | | [Newell NP-F770](https://shop.newell.pro/pl/akumulatory-do-aparatow-fotograficznych-i-kamer/1233-akumulator-newell-zamiennik-np-f770-do-sony-5901891108774.html) | 5200 mAh (38.5 Wh) | Mid-range | | [Newell NP-F970](https://shop.newell.pro/pl/akumulatory-do-aparatow-fotograficznych-i-kamer/870-akumulator-newell-zamiennik-np-f970-do-sony-5901891100822.html) | 9600 mAh (71 Wh) | Longest | See [Battery](https://docs.web3pi.io/ups/hardware/battery/index.md) for charging behavior and swap procedure. ## Interfaces | Interface | Details | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | USB serial | Over the **OUT** cable; the UPS enumerates on the Pi as a `Web3_Pi_UPS` serial device — telemetry, event logging, graceful low-battery shutdown, and remote restart commands via the companion service | | Display | 64 × 32 px monochrome OLED status display | | Buttons | 2 push-buttons — screen navigation and local settings menu | | Buzzer | Audible alarms (power loss, low battery) and UI feedback; can be muted | | LTE-M module | Internal M.2 card with an ESP32-S3 controller and a SIMCom SIM7080G modem (LTE-M / Cat-M1); pre-installed on production units together with a 1NCE nano-SIM and data plan. The UPS is fully functional without it — remote monitoring details in [Connectivity](https://docs.web3pi.io/ups/connectivity/index.md) | ## Physical | Parameter | Value | | ----------------------- | -------------------------------------------------------------------------------------- | | Cooling | Passive — fanless, silent | | Form factor | Compact standalone enclosure; connects by cable only (no GPIO header, no HAT stacking) | | Enclosure compatibility | Works with any Raspberry Pi 5 case | | Rear panel | USB-C **IN** + DC barrel jack |