# Raspberry Pi: Complete Setup and Management Guide

### Overview

The Lynx Raspberry Pi ISO is a slightly modified version of the Raspberry Pi Foundation release of [Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/) designed to automatically set up and manage a Lynx cryptocurrency node on Raspberry Pi devices. This pre-configured image eliminates the complexity of manual node setup by providing a plug-and-play solution that handles everything from initial system configuration to ongoing blockchain synchronization.

### What Makes This ISO Special

#### Automated Node Deployment

The custom ISO transforms a standard Raspberry Pi OS Lite 64-bit ARM image into a specialized Lynx node environment. Upon first boot, the system automatically:

* Downloads and installs the latest Lynx ARM binaries
* Configures system services for optimal node operation
* Sets up memory management with appropriate swap configuration
* Establishes automated maintenance routines
* Provides an intuitive command-line interface for node management

#### Built-in Intelligence

The system includes sophisticated monitoring and maintenance capabilities:

* **Self-healing**: Automatically restarts services if they fail
* **Resource optimization**: Manages memory and swap to prevent crashes
* **Sync monitoring**: Tracks blockchain synchronization progress
* **Network resilience**: Handles network connectivity issues gracefully
* **Update management**: Maintains system components automatically

### System Requirements

#### Hardware Requirements

* **Raspberry Pi 4** (4GB RAM minimum, 8GB recommended)
* **MicroSD Card**: 32GB minimum (64GB+ recommended for long-term operation)
* **Network Connection**: Ethernet cable or WiFi capability
* **Power Supply**: Official Raspberry Pi 4 power adapter (5V/3A USB-C)

#### Network Requirements

* Stable internet connection for initial setup and blockchain synchronization
* Port 22566 available for P2P networking (default Lynx port)
* Outbound HTTPS access for updates and downloads

### Flashing the SD Card

#### Required Software

Download and install one of these SD card flashing tools:

* **Raspberry Pi Imager** - Available at [rpi.org](https://www.raspberrypi.org/software/)

#### Step-by-Step Flashing Process

**Using Raspberry Pi Imager**

1. **Download the Lynx ISO**
   * Obtain the latest `YYYY-MM-DD-Lynx-RPI-ISO.img.xz` file from the [official Lynx releases](https://github.com/getlynx/Lynx/releases)
   * Save it to your computer in an easily accessible location
2. **Prepare Your SD Card**
   * Insert a 32GB+ microSD card into your computer's card reader
   * Ensure the card is empty or that you're comfortable losing all existing data
3. **Flash the Image**
   * Launch Raspberry Pi Imager
   * Click "Choose OS" → "Use custom" and select your downloaded `.img.xz` file
   * Select your SD card from the storage options
   * Under Settings, be sure to enter your WiFi credentials and default username and password. This is required if you plan to log into your Pi later and enable staking.

     <figure><img src="https://972178944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk329MgO7amkh5XzTug%2Fuploads%2FJ4ekWNd0gyU2x82ZJIG3%2FScreenshot%202025-07-28%20at%207.25.12%E2%80%AFPM.png?alt=media&#x26;token=d8cd9f95-74e9-4381-8429-611d54ede5cd" alt=""><figcaption></figcaption></figure>
   * Click "Write" and wait for the process to complete (typically 1-3 minutes)
4. **Verify the Flash**
   * The imager will automatically verify the write process
   * Safely eject the SD card when prompted

### First Boot Process

#### What Happens Automatically

When you insert the SD card and power on your Raspberry Pi, the following sequence occurs automatically:

**Phase 1: System Initialization (0-60 seconds)**

* Standard Raspberry Pi OS boot process
* Network interface configuration
* System service startup
* IP address assignment display

**Phase 2: Network Preparation (60-90 seconds)**

* 60-second waiting period for network stabilization
* Network connectivity testing (ping to 8.8.8.8)
* If network fails: automatic reboot and retry

**Phase 3: Lynx Installation (90 seconds - 5 minutes)**

* Download of the [latest builder script](https://github.com/getlynx/Lynx/blob/main/contrib/pi/builder.sh) from GitHub
* System optimization (swap configuration)
* Lynx binary download and installation
* Service configuration and startup

**Phase 4: Node Initialization (5+ minutes)**

* Lynx daemon startup
* Blockchain synchronization begins
* Automated monitoring system activation
* User interface setup completion

#### Monitoring First Boot

You can monitor the progress, as root, by connecting a monitor and keyboard, or via SSH:

**Via Monitor:**

* Connect HDMI monitor and USB keyboard
* Watch the console output for progress updates
* IP address will be displayed early in the boot process

**Via SSH:**

* Use the displayed IP address to connect: `ssh [username]@[IP_ADDRESS]`
* Be sure to run `sudo su` - you must be root to interact with the system
* Default credentials you entered with Pi Imager
* Monitor logs: `jou`

### Understanding the Custom ISO Components

#### Automated Setup Script (rc.local)

The ISO includes a custom `/etc/rc.local` file that:

* Displays network information
* Implements intelligent network waiting
* Downloads the latest node software
* Handles network failure scenarios gracefully
* Self-disables after successful setup

#### Builder Script Functionality

The main builder script (`builder.sh`) provides:

* **System Optimization**: Automatic swap file management
* **Binary Management**: Downloads and installs Lynx binaries
* **Service Management**: Creates and manages systemd services
* **Monitoring**: Tracks synchronization and system health
* **User Experience**: Sets up command aliases and help system

#### Systemd Services Created

The system creates several services for optimal operation:

**lynx.service**: Main Lynx daemon service

* Automatically starts the Lynx node
* Handles graceful shutdowns
* Includes restart policies for reliability

**builder.service & builder.timer**: Maintenance system

* Runs every 12 minutes during initial sync
* Monitors blockchain synchronization progress
* Self-disables once sync is complete
* Provides ongoing system health checks

### Node Management Interface

Once your Lynx node is running, you'll have access to a comprehensive command-line interface designed for both beginners and advanced users.

#### Accessing the Management Interface

**Local Access:**

* Connect monitor and keyboard to your Raspberry Pi
* Log in with default credentials (example username: `pi`, password: `raspberry`)
* The help interface appears automatically after running `sudo su` to switch to the root account

**Remote Access via SSH:**

```bash
ssh pi@[YOUR_PI_IP_ADDRESS]
```

#### Command Categories

**Wallet Management Commands**

**`gba` - Get Wallet Balances**

```bash
gba
```

Displays all wallet balances including confirmed, unconfirmed, and staking balances. Essential for monitoring your node's financial status.

**`gna` - Generate New Address**

```bash
gna
```

Creates a new receiving address for your wallet. Use this when you need to receive Lynx coins.

**`lag` - List Address Groupings**

```bash
lag
```

Shows how addresses are grouped in your wallet, helpful for understanding coin organization and privacy.

**`sta` - Send to Address**

```bash
sta [address] [amount]
```

Sends Lynx coins to a specified address. Example:

```bash
sta KLynxAddress123... 10.5
```

**`swe` - Sweep Wallet**

```bash
swe [address]
```

Sends all available funds to an address, useful for wallet consolidation or moving funds.

**System Monitoring Commands**

**`lyv` - Show Lynx Version**

```bash
lyv
```

Displays the current Lynx daemon version and build information.

**`gbi` - Get Blockchain Info**

```bash
gbi
```

Shows comprehensive blockchain synchronization status including:

* Current block height
* Sync progress percentage
* Network difficulty
* Verification progress

**`lss` - Service Status**

```bash
lss
```

Displays the current status of the Lynx systemd service, including whether it's running, any recent errors, and resource usage.

**`jou` - View System Logs**

```bash
jou [lines] [-f]
```

Shows real-time builder script logs, essential for troubleshooting and monitoring system health.

**Configuration and Maintenance**

**`lyc` - Edit Configuration**

```bash
 lyc [-e] 
```

Opens the Lynx configuration file in nano editor for advanced users who need to modify node settings.

**`lyl` - View Debug Logs**

```bash
 lyl [lines] [-f]
```

Displays real-time Lynx daemon debug logs, crucial for troubleshooting blockchain synchronization issues.

**`lyr` - Restart Node**

```bash
lyr
```

Safely stops and restarts the Lynx daemon, clearing debug logs in the process. Use when the node appears stuck or unresponsive.

**`h` - Show Lynx Help**

```bash
h
```

Displays comprehensive help for all available Lynx CLI commands.

**Utility Commands**

**`htop` - System Monitor**

```bash
htop
```

Interactive system resource monitor showing CPU, memory, and process information.

**`motd` - Show Help Interface**

```bash
motd
```

Redisplays the complete command help interface with current staking statistics.

#### Understanding the Help Interface

The system displays an ASCII art interface showing:

**Node Statistics**

* **Stakes Won**: Number of proof-of-stake blocks found in the last 24 hours
* **Real-time Updates**: Statistics update each time you run `motd`

**Command Categories**

Commands are organized into logical groups:

* **Wallet Commands**: For managing coins and addresses
* **System Commands**: For node operation and troubleshooting
* **Useful Commands**: For system monitoring and help

**Resource Links**

Direct links to:

* Complete project documentation
* Permanent file storage solutions
* Blockchain explorer
* Trading platforms

### Blockchain Synchronization Process

#### Understanding Sync Phases

**Initial Block Download**

* Downloads the entire blockchain from network peers
* Can take 2-24 hours depending on network speed (typically 4 hours with average broadband speeds)
* Progress visible via `gbi` command
* System automatically optimizes during this phase

**Verification Phase**

* Validates downloaded blocks
* Ensures blockchain integrity
* May restart daemon periodically for optimization (normal behavior, do not interrupt)
* Normal behavior during initial setup

**Maintenance Mode**

* Activated once sync is complete
* Minimal resource usage
* Automatic monitoring disabled
* Node ready for staking and transactions

#### Monitoring Sync Progress

**Check Sync Status:**

```bash
gbi
```

Look for these key indicators:

* `"initialblockdownload": false` - Sync complete
* `"verificationprogress": 1.0` - Verification complete
* `"blocks"` vs `"headers"` - Should be equal when synced

**Monitor Resource Usage:**

```bash
htop
```

During sync:

* CPU usage will be moderate to high
* CPU usage will be <1% when sync is complete
* Memory usage should remain stable
* Disk I/O will be active

**View Sync Logs:**

```bash
lyl
```

Watch for:

* Block download progress
* Peer connections
* Any error messages

#### Troubleshooting Sync Issues

**Node Appears Stuck:**

```bash
lynx  # Restart the daemon
```

**Check Network Connectivity:**

```bash
ping 8.8.8.8
```

**Verify Service Status:**

```bash
lss
```

**Review System Logs:**

```bash
jou
```

### System Maintenance and Updates

#### Automatic Maintenance Features

The system includes sophisticated automatic maintenance:

**Resource Management**

* Automatic swap file creation and management
* Memory optimization during blockchain sync
* Disk space monitoring and cleanup

**Service Management**

* Automatic daemon restarts during sync phase
* Health monitoring and recovery
* Log rotation and cleanup

**Update Management**

* Binary updates (manual process recommended)
* System package updates (standard apt process)
* Reflashing the SD card is recommended after a wallet sweep.

{% hint style="danger" %}
After sweeping a wallet, verify that coins are received at the remote address for safety. If staking was enabled, the movement of immature coins can delay the transaction. Only when coins are received, should you re-image the SD card.
{% endhint %}

#### Manual Maintenance Tasks

**Check System Health:**

```bash
lss           # Service status
htop          # Resource usage
jou           # Recent system logs
```

**Update System Packages:**

```bash
sudo apt update && sudo apt upgrade -y
```

**Monitor Disk Space:**

```bash
df -h         # Check available space
```

**Backup Wallet:**

```bash
# Copy wallet.dat to external storage
cp ~/.lynx/wallet.dat /path/to/backup/
```

### Security Considerations

#### Network Security

* Change default passwords immediately after first boot
* Enable SSH key authentication for remote access
* Consider firewall configuration for additional security
* Regularly monitor for unauthorized access attempts

#### Wallet Security

* **Backup Strategy**: Regular wallet.dat backups to multiple locations
* **Encryption**: Consider wallet encryption for added security
* **Access Control**: Limit physical and network access to the device
* **Updates**: Keep system and Lynx software updated

#### System Security

* **Regular Updates**: Apply system security updates promptly
* **Monitoring**: Review logs regularly for suspicious activity
* **Network**: Use secure networks and consider VPN for remote access

### Troubleshooting Common Issues

#### Node Won't Start

**Symptoms**: `lss` shows service as failed&#x20;

**Solutions**:

1. Check system resources: `htop`
2. Review error logs: `jou`
3. Restart service: `lyr`
4. Check disk space: `df -h`

#### Slow Synchronization

**Symptoms**: Sync progress is very slow&#x20;

**Solutions**:

1. Check network speed and stability
2. Verify sufficient disk space
3. Monitor resource usage: `htop`
4. Consider restarting daemon: `lyr`

#### Cannot Connect Remotely

**Symptoms**: SSH connection fails&#x20;

**Solutions**:

1. Verify Pi is powered on and booted
2. Check network connectivity
3. Confirm IP address hasn't changed
4. Verify SSH is enabled

#### Command Not Found Errors

**Symptoms**: Custom aliases don't work&#x20;

**Solutions**:

1. Re-login to reload bashrc
2. Manually run: `source ~/.bashrc`
3. Check if setup completed: `h`

### Wallet Issues

**Symptoms**: Cannot access wallet functions&#x20;

**Solutions**:

1. Verify daemon is running: `lss`
2. Check RPC credentials in config: `lyc`
3. Review debug logs: `lyl`
4. Restart daemon: `lyr`

### Getting Help and Support

#### Documentation Resources

* **Complete Documentation**: <https://docs.getlynx.io/>
* **API Reference**: Available through `h` command
* **Blockchain Explorer**: <https://chainz.cryptoid.info/lynx/>

#### Community Support

* **Trading Platform**: <https://freixlite.com/market/LYNX/LTC>
* **File Storage**: <https://clevver.org/>
* **GitHub Repository**: Source code and issue tracking

#### System Information Commands

When seeking help, these commands provide useful diagnostic information:

```bash
h             # Show current system status
lss           # Service status
gbi           # Blockchain sync status
jou           # Recent system logs
lyl           # Lynx daemon logs
htop          # Resource usage
```

### Conclusion

The Lynx Raspberry Pi ISO provides a complete, automated solution for running a Lynx cryptocurrency node. From initial flashing to ongoing management, the system handles complex tasks automatically while providing powerful tools for advanced users. The intuitive command interface makes node management accessible to users of all technical levels, while the robust automation ensures reliable operation with minimal intervention.

By following this guide, you'll have a fully functional Lynx node contributing to the network's security and decentralization while potentially earning staking rewards. The system's self-maintaining design means you can focus on using and enjoying your Lynx node rather than managing its technical complexities.