Hello,
We have prepared one high level architecture document for new modem
upgrader module. We are still in designing and implementation phase.
Let me know if you need it in another standard format.
PFA
Thanks and regards,
Rahul Bhagwat.
On Wednesday, 24 December 2025 at 12:02:54 UTC+5:30 Rahul Bhagwat wrote:
> Hello Federico,
>
> Thanks for detailed Explanation. Got enough information to start with new
> Module development.
>
> We have started working on design document. I will share it in next two
> weeks.
>
> Thanks and regards,
> Rahul Bhagwat
>
> On Thursday, 18 December 2025 at 01:34:58 UTC+5:30 f.capoano wrote:
>
>> Hello Rahul,
>>
>> Thank you for the detailed message and for your interest in contributing
>> to OpenWISP.
>>
>> At the moment there is no formal or predefined procedure for proposing
>> and accepting new core modules. Inclusion in the OpenWISP ecosystem IMHO
>> depends mainly on two factors:
>>
>> -
>>
>> whether the proposed functionality aligns with OpenWISP’s long term
>> scope and there's enough interest from the community to use it
>> -
>>
>> whether the project has sufficient resources and active maintainers
>> to sustainably maintain the additional code over time
>>
>> For this reason, new functionality is usually developed and validated
>> first as an extension of OpenWISP: the core team also does this: we first
>> implement what we need for our own deployments and after an initial period
>> of validation the feature is proposed for inclusion.
>>
>> Our general recommendation is to focus initially on making your specific
>> use case work for your use case and :
>>
>> -
>>
>> design and implement the module in a way that can be integrated with
>> existing OpenWISP deployments
>> -
>>
>> document your code, making sure there's instructions on how to
>> install it and use it
>> -
>>
>> publish the code publicly and share it on the OpenWISP mailing list
>>
>> If the module gains adoption, proves useful to a broader audience, and
>> there are contributors willing to maintain it long term, inclusion as an
>> official OpenWISP module can be evaluated at a later stage.
>>
>> In the worst case, the module remains a third party extension maintained
>> by your team, which is perfectly acceptable and still valuable to the
>> community.
>>
>> Feel free to share design details or early drafts on the mailing list if
>> you would like feedback while you are working on it.
>> Best regards
>> *Federico Capoano*
>> OpenWISP OÜ
>> Kotkapoja tn 2a-10, 10615, Harju maakond, Tallinn, Estonia
>> VAT: EE101989729
>> +372 59361689 <+372%205936%201689>
>> *openwisp.io* <http://openwisp.io>
>>
>>
>> On Fri, 12 Dec 2025 at 16:46, Rahul Bhagwat <[email protected]> wrote:
>>
>>> Hello Everyone,
>>>
>>> My Self Rahul Bhagwat, Lead Engineer at Softdel Systems Pvt. Ltd. We are
>>> working on behalf of Railhead Corporation for one of proposal of
>>> integration of new module in OpenWISP.
>>>
>>> We are exploring the possibility of contributing a new module to the
>>> OpenWISP ecosystem, focused on firmware upgrade management for 5G modems
>>> connected to OpenWrt-based devices. The intent is to design a module
>>> similar to existing openwisp-firmware-upgrader that can handle detection,
>>> version tracking, and remote firmware upgrade of cellular modems.
>>>
>>> The idea is to design a new module that allows OpenWISP to host 5G/LTE
>>> modem firmware binaries (from any vendor) and push them to OpenWRT-based
>>> devices, where a modem-specific script will execute the actual upgrade on
>>> the modem. The modem-specific script/tool must be installed on device by
>>> the customer, and it will differ for each modem vendor.
>>>
>>> For the initial implementation, we are focusing on supporting the Telit
>>> FN990A modem firmware upgrade. As customers begin using this module, they
>>> can install their own vendor-specific scripts/tools and validate the
>>> upgrade process for other modem models.
>>> To begin with, I would like to understand the recommended approach for
>>> proposing and developing new modules intended for inclusion in the core
>>> OpenWISP ecosystem. I’m looking for guidance on the preferred process such
>>> as architectural discussions, design reviews, and the expected steps before
>>> starting development to ensure the contribution aligns well with OpenWISP’s
>>> long-term direction.
>>>
>>> Looking forward to your guidance and queries / suggestions.
>>>
>>> Thanks and regards,
>>> Rahul Bhagwat.
>>>
>>> --
>>> You received this message because you are subscribed to the Google
>>> Groups "OpenWISP" group.
>>> To unsubscribe from this group and stop receiving emails from it, send
>>> an email to [email protected].
>>> To view this discussion, visit
>>> https://groups.google.com/d/msgid/openwisp/78f07992-da85-430e-abf7-9cca4cc297b5n%40googlegroups.com
>>>
>>> <https://groups.google.com/d/msgid/openwisp/78f07992-da85-430e-abf7-9cca4cc297b5n%40googlegroups.com?utm_medium=email&utm_source=footer>
>>> .
>>>
>>
--
You received this message because you are subscribed to the Google Groups
"OpenWISP" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion, visit
https://groups.google.com/d/msgid/openwisp/2ebd6e8f-cb8c-4d50-a873-ca4e8a18e526n%40googlegroups.com.
# OpenWISP Modem Firmware Upgrader - Technical Overview
## Executive Summary
The **openwisp-modem-upgrader** module extends OpenWISP's firmware management capabilities to support 5G/LTE cellular modem firmware upgrades on OpenWrt-based devices. Following the proven architecture of `openwisp-firmware-upgrader`, it provides centralized management of modem firmware with real-time progress tracking, batch operations, and vendor-neutral design.
**Key Features:**
- Centralized modem firmware version tracking and binary management
- Remote firmware upgrades with real-time progress telemetry from devices
- Batch upgrade operations across device fleets with comprehensive monitoring
- Vendor-agnostic architecture supporting multiple modem manufacturers
- Django swapper pattern for complete model customization
- RESTful API for programmatic access and device telemetry
**Initial Target:** Modem Telit FN990A modems with modem specific script upgrade tools
---
## System Architecture
### Component Overview
The system operates across two layers: **OpenWISP Server** (centralized management) and **OpenWrt Device** (edge execution).
**Server-Side Components:**
- **Models Layer**: Swappable Django models for firmware metadata, device associations, and upgrade operations
- **Admin Interface**: Device inlines showing "Modem Firmware" and "Recent Modem Firmware Upgrades"
- **REST API**: Full CRUD operations, batch upgrade management, and device telemetry endpoints
- **Background Tasks**: Celery-based queue for upgrade execution, batch orchestration, and automation
- **Private Storage**: Secure, permission-checked firmware file storage with organization isolation
**Device-Side Requirements:**
- Customer-installed vendor-specific modem upgrade tool (modem specific script)
- OpenWISP-provided upgrade script that receives firmware via SCP, executes vendor tool, and reports progress
- SSH connectivity for remote command execution
### Architecture Diagram
```
┌─────────────────────────────────────────────────┐
│ OpenWISP Server │
│ ┌──────────────────────────────────────────┐ │
│ │ openwisp_modem_upgrader (Django App) │ │
│ │ - Models (Swappable) │ │
│ │ - Admin (Device Inlines) │ │
│ │ - API (DRF) │ │
│ │ - Tasks (Celery) │ │
│ │ - Private Storage │ │
│ └──────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────┐ │
│ │ OpenWISP Controller │ │
│ │ - Device/Organization Models │ │
│ │ - DeviceConnection (SSH) │ │
│ └──────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────┘
│ SSH/SCP
┌────────────────────▼────────────────────────────┐
│ OpenWrt Device │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Upgrade │───▶│ Vendor Tool | |
│ │ Script │ │ ( script) │ │
│ │ - Progress │ └──────────┬───────────┘ │
│ │ Updates │ │ │
│ └──────────────┘ ┌─────────▼───────────┐ │
│ │ 5G/LTE Modem │ │
│ │ (Modem Telit FN990 │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────┘
```
---
## Data Model
### Core Entities
**ModemCategory** - Groups firmware by vendor/model family (organization-scoped)
**ModemBuild** - Represents a specific firmware version
- `version`: Firmware version string (e.g., "M0F.050003.03")
- `modem_model`: Hardware identifier (e.g., "Modem Telit FN990A")
- `changelog`: Release notes in Markdown
- Relationship: Belongs to ModemCategory, has many ModemFirmwareImages
**ModemFirmwareImage** - Stores actual firmware binaries
- `file`: FileField with private storage
- `type`: Upgrade tool type (generic script)
- `boards`: JSONField listing compatible hardware boards
- Downloads require authentication and organization permissions
**DeviceModemFirmware** - Links devices to current modem firmware
- `device`: ForeignKey to Device (openwisp-controller)
- `image`: ForeignKey to ModemFirmwareImage (nullable)
- `installed`: Boolean indicating current installation status
- Auto-created for new devices; triggers upgrade on save with `upgrade_options`
**ModemUpgradeOperation** - Tracks individual upgrade execution
- `status`: idle → in-progress → success/failed/aborted
- `progress_percent`: 0-100 (updated by device telemetry)
- `log`: Full execution output
- `upgrade_options`: JSONField validated against upgrader schema
**ModemBatchUpgradeOperation** - Orchestrates mass upgrades
- Linked to ModemBuild with organization-wide scope
- Computed metrics: progress_report, success_rate, failed_rate, aborted_rate
- Methods: `dry_run()` (preview), `upgrade()` (execute)
**All models are swappable** using Django swapper pattern for customization.
---
## Upgrade Workflow
### Single Device Upgrade
1. **Admin Selection**: User selects modem firmware in Device admin inline
2. **Validation**: System validates image compatibility with device hardware
3. **Operation Creation**: `DeviceModemFirmware.save()` creates `ModemUpgradeOperation`
4. **Task Queuing**: Celery task `upgrade_modem_firmware.delay()` queued
5. **Execution Stages**:
- **Transfer (0-10%)**: SCP firmware to device
- **Verify (10-20%)**: Optional checksum validation
- **Execute (20-90%)**: Run vendor tool with progress callbacks
- **Reboot (90-95%)**: Wait for modem restart
- **Verify (95-100%)**: Confirm new firmware version
6. **Completion**: Operation marked success/failed with full logs
### Batch Upgrade
1. **Admin Action**: User selects ModemBuild and clicks "Mass-upgrade device modems"
2. **Preview**: System displays affected devices and collects upgrade options
3. **Orchestration**: `ModemBatchUpgradeOperation` created, Celery task queued
4. **Parallel Execution**: Individual `ModemUpgradeOperation` created and queued for each device
5. **Progress Tracking**: Batch operation aggregates individual operation statuses
### Progress Telemetry
During upgrade, device script sends HTTP POST requests every 5-10 seconds to:
```
/api/v1/modem-upgrader/upgrade-operation/{id}/
Payload: {"progress_percent": 65, "status": "in-progress"}
```
Server updates operation record; admin UI displays real-time progress bars.
---
## Upgrader System
### Pluggable Architecture
Each modem vendor has a dedicated upgrader class implementing:
```python
class BaseModemUpgrader:
SCHEMA = {...} # JSON schema for upgrade options
def upgrade(self, operation, firmware_path, upgrade_options):
"""Execute upgrade with progress tracking"""
raise NotImplementedError
```
**Modem FN990A Example:**
- Schema defines: `tool_path`, `transfer_timeout`, `upgrade_timeout`, `verify_checksum`, `progress_callback_interval`
- Implements 5-stage upgrade with percentage updates
- Handles errors with retry/no-retry classification
**Adding New Modems:**
1. Create upgrader class in `openwisp_modem_upgrader/upgraders/`
2. Define vendor-specific JSON schema
3. Implement `upgrade()` with progress tracking
4. Register in settings: `OPENWISP_MODEM_UPGRADERS_MAP`
---
## REST API
### Key Endpoints
| Endpoint | Methods | Purpose |
|----------|---------|---------|
| `/api/v1/modem-upgrader/build/` | GET, POST | Manage modem builds |
| `/api/v1/modem-upgrader/firmware-image/{id}/download/` | GET | Download firmware (auth required) |
| `/api/v1/modem-upgrader/batch-upgrade-operation/` | GET, POST | Batch upgrade management |
| `/api/v1/modem-upgrader/upgrade-operation/{id}/` | GET, PATCH | Operation details + progress updates |
| `/api/v1/modem-upgrader/device-firmware/` | GET, POST | Device firmware associations |
**Authentication:** Token-based (DRF)
**Permissions:** Organization-scoped with automatic filtering
**Rate Limiting:** 1000 requests/minute per user
---
## Security & Error Handling
### Security Measures
- **Private Storage**: Firmware files require authenticated, permission-checked downloads
- **Organization Isolation**: All data scoped to user`s organization(s)
- **SSH Security**: Encrypted SCP transfer, parameterized commands, timeout protection
- **Input Validation**: JSON schema validation for all upgrade options
### Error Handling
**Exception Hierarchy:**
- `RecoverableModemFailure`: Temporary errors, Celery retries with exponential backoff (max 3 attempts)
- `IrrecoverableModemFailure`: Permanent errors, immediate failure without retry
Examples: ConnectionTimeout (recoverable), ChecksumMismatch (irrecoverable)
---
### System Requirements
- **Celery Workers**: Minimum 2 for concurrent upgrades
- **Redis**: Message broker and result backend
- **Disk Space**: 100MB-1GB per firmware file
- **Network**: SSH access from OpenWISP server to all devices
---
## Extensibility
All models support Django swapper for customization. Example:
```python
from openwisp_modem_upgrader.base.models import AbstractModemBuild
class CustomModemBuild(AbstractModemBuild):
certification_status = models.CharField(max_length=50)
class Meta(AbstractModemBuild.Meta):
abstract = False
swappable = swapper.swappable_setting('modem_upgrader', 'ModemBuild')
# settings.py
OPENWISP_MODEM_BUILD_MODEL = 'myapp.CustomModemBuild'
```
