---
title: Kepware to LitmusEdge Migrator
slug: solutions/kepware-to-litmusedge-migrator
docTags: 
createdAt: 2025-11-03T19:34:50.426Z
---

## Overview

![](https://api.archbee.com/api/optimize/SSUUxKZUk9bFTEPNn_6Zo/rjXu-3_9XRHSfgFXiS6Xl-20251104-012054.png)

The Kepware to LitmusEdge Migrator is a web-based tool that automatically converts Kepware project files into LitmusEdge-compatible format. The migrator analyzes Kepware JSON exports and performs intelligent transformations including driver mapping, address translation, and configuration preservation.

**Key capabilities:**

- Automatic driver mapping from Kepware to LitmusEdge equivalents
- Address translation for Modbus, Siemens, Allen-Bradley, and Toyopuc protocols
- Web-based interface for file upload and processing
- Direct template application to LitmusEdge instances using OAuth2, an API token, or username and password
- Detailed migration logs with unmapped address reporting, exportable as text or HTML
- Light and dark themes

## Supported Drivers

| Kepware Driver                      | LitmusEdge Driver                 |
| ----------------------------------- | --------------------------------- |
| Modbus TCP/IP Ethernet              | Modbus TCP                        |
| Siemens S7 Plus Ethernet            | Siemens S7CommPlus                |
| Siemens TCP/IP Ethernet             | Siemens S7                        |
| Allen-Bradley ControlLogix Ethernet | AB CompactLogix Ethernet Advanced |
| Allen-Bradley CompactLogix Ethernet | AB CompactLogix Ethernet Advanced |
| Allen-Bradley MicroLogix Ethernet   | AB EthernetIP Ethernet            |
| Toyopuc PC3/PC2 Ethernet            | JTEKT Toyopuc CMP-Link            |
| Fanuc Focas Ethernet                | Fanuc Focas (Coming soon)         |

## Running the Application

### Prerequisites

- Docker installed on your system
- Kepware project exported as JSON file
- (Optional) LitmusEdge instance with OAuth2 client credentials, an API token, or a username and password for direct template application

### Deployment Steps

1. Download `kepware-migrator.tar.gz` and load the Docker image:

```bash
docker load -i kepware-migrator.tar.gz
```

2. Run the container:

```bash
docker run -d -p 4001:4001 --name kepware-migrator kepware-migrator:latest
```

3. Access the application at `http://localhost:4001`

## Using the Migrator

### Step 1: Export Kepware Project

1. Open Kepware Configuration Manager
2. Go to **File > Save As**
3. Select **JSON format**
4. Save the file to your computer

### Step 2: Upload and Convert

1. Navigate to the migrator home page at `http://localhost:4001`
2. Click **"Choose File"** and select your Kepware JSON file
3. Click **"Upload"**
4. Wait for processing to complete (typically a few seconds)

### Step 3: Review Results

After processing, a new entry appears under **Recent Upload Activity**. Click it to expand the details:

- **Unmapped Kepware Addresses**: tags that could not be converted, with the address and the reason
- **Successful Migration Summary**: the converted channels and the devices under each one

Use **Copy Logs** or **Download Logs** to keep a record of the migration. Logs are stored in your browser, and **Clear Logs** removes them.

### Step 4: Download Converted Configuration

1. Scroll to the **"Processed Files"** section
2. Click **"Download"** to download the LitmusEdge-compatible JSON

Use the delete button next to a file to remove it from the migrator.

### Step 5: Apply to LitmusEdge

### Option A: Direct Application (Requires Configuration)

**Note:** The "Apply to Litmus Edge" feature only works after you configure your LitmusEdge connection on the **Config** page.

1. Click the **Config** tab in the migrator interface
2. Enter the **Edge URL** (e.g., `192.168.1.100` or `https://edge.example.com`). If you leave out the scheme, HTTPS is assumed.
3. Choose an authentication method and enter its credentials:
   - **OAuth2 client**: API Client ID and API Client Secret
   - **API token**: an API token (or JWT) generated in LitmusEdge
   - **Username / password**: a local LitmusEdge user
4. Click **Save Configuration**. The status row at the top of the page shows **Configured** once the URL and credentials are set.
5. Return to the **Home** page
6. In the "Processed Files" section, click **"Apply to Litmus Edge"**

![Config page with an OAuth2 connection configured](https://images.ctfassets.net/7xdd0wzmxlfo/1O3GXkT3wRYWaCYwCCR1jg/541ae19c5faae5c2e2cc4e31ca463dc4/kepware-migrator-5-config.png)

**Warning:** Applying a template replaces existing flows in your LitmusEdge instance. Back up your current configuration before proceeding.

### Option B: Manual Upload

1. Log in to your LitmusEdge interface
2. Navigate to **System > Device Management > Template**
3. Click **"Upload Template"**
4. Select the downloaded JSON file
5. Review and test the imported configuration

## Configuration

The migrator supports the following environment variables:

| Variable                 | Description                                        | Example              |
| ------------------------ | -------------------------------------------------- | -------------------- |
| `EDGE_URL`               | LitmusEdge instance URL (HTTPS if no scheme)       | `192.168.1.100`      |
| `EDGE_AUTH_METHOD`       | `oauth`, `token`, or `jwt` (username and password) | `oauth`              |
| `EDGE_API_CLIENT_ID`     | OAuth2 Client ID (for `oauth`)                     | `your_client_id`     |
| `EDGE_API_CLIENT_SECRET` | OAuth2 Client Secret (for `oauth`)                 | `your_client_secret` |
| `EDGE_API_TOKEN`         | API token or JWT (for `token`)                     | `your_api_token`     |
| `EDGE_USERNAME`          | LitmusEdge username (for `jwt`)                    | `admin`              |
| `EDGE_PASSWORD`          | LitmusEdge password (for `jwt`)                    | `your_password`      |

These can be configured through the web interface (**Config** page) or via a `.env` file in the container.

## Troubleshooting

### Port Already in Use

If port 4001 is unavailable, map to a different port:

```bash
docker run -d -p 8080:4001 --name kepware-migrator kepware-migrator:latest
```

Access the application at `http://localhost:8080`

### Migration Produces Unmapped Addresses

Unmapped addresses indicate tags that couldn't be automatically converted, typically due to:

- Unsupported address formats
- Custom addressing schemes
- Driver-specific syntax not recognized
- Kepware data types with no LitmusEdge equivalent for that address

These addresses are listed in the migration log and require manual configuration in LitmusEdge.

### Template Application Fails or Button Not Available

The "Apply to Litmus Edge" feature requires configuration to be set before it can be used. Verify the following:

1. The Edge URL and credentials for the selected authentication method are configured on the **Config** page
2. Configuration has been saved successfully
3. LitmusEdge credentials are correct
4. LitmusEdge instance is accessible from the migrator container
5. You have a valid LitmusEdge license
6. Network connectivity exists between the migrator and LitmusEdge

If applying the template fails with an authentication error, navigate to the **Config** page and check your LitmusEdge credentials.

### Upload Fails

Ensure:

- File is in JSON format (not .opf or other Kepware format)
- File size is under 16MB
- JSON is valid and not corrupted
- File was exported from Kepware (not manually created)

## Use Cases

### Migrating Legacy Kepware Systems

Organizations transitioning from Kepware to LitmusEdge can accelerate migration by automatically converting existing configurations, preserving years of device and tag definitions while adapting to the new platform.

### Multi-Site Deployments

For companies deploying LitmusEdge across multiple facilities with similar equipment, convert a single Kepware reference project and replicate the configuration across sites with minimal manual work.

### Batch Processing Multiple Projects

Process multiple Kepware projects sequentially, download all converted files, and review unmapped addresses across projects to identify common manual configuration patterns before deployment.

## Best Practices

- **Backup Original Files**: Always retain copies of original Kepware projects before migration
- **Review Unmapped Addresses**: Carefully examine the migration log for unmapped addresses and plan manual configuration
- **Test Incrementally**: After importing to LitmusEdge, test device connections one at a time
- **Verify Device Settings**: Review timeouts, polling rates, and communication parameters in LitmusEdge post-migration
- **Download Migration Logs**: Keep migration logs for reference during troubleshooting and future migrations

## Limitations

- Only Kepware JSON format is supported (not .opf binary format)
- Drivers not in the supported list require manual configuration
- Tag grouping within devices may be flattened depending on driver type
- Some device-specific parameters may require manual adjustment after import
- Template application requires valid LitmusEdge license