# RAUC Bundle Installation

## Overview

Starting with CCLinux OS 4.x, CODESYS Runtime packages are distributed as RAUC (Robust Auto-Update Controller) bundles. RAUC provides atomic, fail-safe updates with cryptographic verification and rollback capability.

## What are RAUC Bundles?

RAUC bundles are signed, compressed update packages that contain:

- **Application filesystem** (`appfs.ext4`): CODESYS runtime binaries, libraries, and dependencies
- **Root filesystem** (optional): Base operating system updates from CCLinux OS
- **Manifest** (`manifest.raucm`): Metadata, slot configuration, and digital signatures
- **Configuration files**: Required for post-installation setup
- **Custom handlers**: Scripts that run during installation for device-specific configuration

### Security Features

- **dm-verity**: Read-only filesystem verification ensures integrity
- **Cryptographic signatures**: Bundles are signed with CrossControl development keys
- **Atomic updates**: Installation either completes fully or rolls back on failure
- **Slot system**: A/B partition scheme allows safe updates without downtime

## Installation

### Prerequisites

- CCpilot device running CCLinux OS 4.2.0 or later
- RAUC installed and configured (included in CCLinux OS)
- Network or USB access to transfer the bundle
- Sufficient free space in the target slot

### Installing a Bundle

1. **Transfer the bundle** to the device:
   ```sh
   scp codesys-ccl4_visu_V3.5.21.20-10_v1x00.raucb ccs@<device-ip>:/data/home/ccs/
   ```

2. **Install using RAUC**:
   ```sh
   rauc install /data/home/ccs/codesys-ccl4_visu_V3.5.21.20-10_v1x00.raucb
   ```

3. **Reboot** to activate the new slot (if required):
   ```sh
   reboot
   ```

### Installation Process

When you install a RAUC bundle, the following happens automatically:

1. **Signature verification**: RAUC verifies the bundle is signed by a trusted key
2. **Bundle extraction**: The bundle is mounted and contents are extracted
3. **Filesystem updates**: Application filesystem is written to the inactive slot
4. **Custom handler execution**: `hook.sh` runs to configure the system:
   - Creates CODESYS configuration directories
   - Copies `CODESYSControl.cfg` to user configuration location
   - Sets up CodeMeter licensing directories and permissions
   - Configures CodeMeter server settings
   - Creates package marker file for tracking installed version
   - Triggers USB device updates for CodeMeter dongles

5. **Slot activation**: The newly updated slot is marked as bootable
6. **Reboot** (manual or automatic): System boots into the updated partition

### Post-Installation

After installation and reboot:

- CODESYS runtime is automatically started via systemd services
- CodeMeter licensing service is configured and running
- Application is accessible via network (default port 1217 for CODESYS, 8080 for WebVisu)

Check service status:
```sh
systemctl status codesys.service
systemctl status codemeter.service
```

View CODESYS logs:
```sh
journalctl -u codesys.service -f
```

## Bundle Variants

Four variants are available for each device type:

| Variant | Description | Includes Visu | Includes WebVisu |
|---------|-------------|---------------|------------------|
| **novisu** | Runtime only | ❌ | ❌ |
| **visu** | Local visualization | ✅ | ❌ |
| **webvisu** | Web visualization | ❌ | ✅ |
| **visuwebvisu** | Both visualizations | ✅ | ✅ |

Choose the variant that matches your CODESYS license and application requirements.

## Device Types

RAUC bundles are device-specific. Supported devices:

- **v700**: CCpilot V700
- **vx10**: CCpilot V510, V705, V710
- **v1x00**: CCpilot V1000, V1200
- **v1x90**: CCpilot V1090, V1290

Always use the bundle matching your device type (indicated in the filename).

## Troubleshooting

### Installation Fails

If installation fails, check the system logs:
```sh
journalctl -u rauc -f
```

Common issues:
- **Signature verification failed**: Bundle may be corrupted or unsigned
- **Insufficient space**: Check available space in target partition
- **Handler script failed**: Check `/var/log/syslog` for custom handler errors

### Rollback

If the new installation doesn't boot correctly, RAUC automatically rolls back to the previous working slot after 3 failed boot attempts.

Manual rollback to previous slot:
```sh
rauc status  # Check which slot is active
# To manually boot to other slot
rauc status mark-active [booted | other]
reboot
```

### Checking Installation Status

View current slot and bundle information:
```sh
rauc status
```

Check installed package version:
```sh
ls -la /data/home/ccs/packages/
```

### CodeMeter License Issues

If CodeMeter is not working after installation:

1. **Check CodeMeter service**:
   ```sh
   systemctl status codemeter.service
   journalctl -u codemeter.service
   ```

2. **Verify license files**:
   ```sh
   ls -la /data/home/ccs/CODESYS/.SoftContainer_CmRuntime.wbb
   ls -la /data/home/ccs/CodeMeter/var/lib/CodeMeter/Backup/Server.ini
   ```

3. **Manually trigger USB detection**:
   ```sh
   udevadm trigger --subsystem-match=usb --attr-match=idVendor=064f
   ```

4. **Restart CodeMeter**:
   ```sh
   systemctl restart codemeter.service
   ```

## Advanced: Bundle Contents

To inspect a RAUC bundle without installing:

```sh
# Extract bundle (requires squashfs-tools)
unsquashfs codesys-ccl4_visu_V3.5.21.20-10_v1x00.raucb

# View contents
ls -la squashfs-root/

# Read manifest
cat squashfs-root/manifest.raucm
```

Bundle structure:
```
squashfs-root/
├── manifest.raucm                          # Bundle manifest
├── appfs.ext4                               # Application filesystem image
├── ccpilot-v1x00-release-v1x00.ext4        # Root filesystem (from CCLinux)
├── hook.sh                        # Post-install script
├── CODESYSControl.cfg                       # CODESYS configuration
├── codesys-launch.sh                        # Launch script
├── Server.ini                               # CodeMeter configuration
├── .SoftContainer_CmRuntime.wbb             # CodeMeter license (optional)
└── .UFC_SoftContainer_CmRuntime.WibuCmLif   # CodeMeter license (optional)
```

## See Also

- [RAUC Documentation](https://rauc.readthedocs.io/)
- [CCLinux OS Update Guide](https://docs.crosscontrol.com/cclinux/)
- [CODESYS Installation Guide](Installation.md)