ModLens & ModLens Sim: Installation and User Guide

Two separate apps that work well together:

Contents

1. What you get
2. Install ModLens on Windows
3. Install ModLens Sim on Windows
4. Install on a Raspberry Pi (both apps)
5. Using ModLens
6. Managing the simulator (ModLens Sim)
7. Test both apps together
8. Troubleshooting
9. Where files are stored

1. What you get

Requirements - Windows: Windows 10 or 11 (64-bit). The app window uses Microsoft Edge WebView2, which is already installed on most PCs. - Raspberry Pi: Pi 3B+, 4 or 5 with Raspberry Pi OS Bookworm (64-bit) or newer. Other Debian/Ubuntu Linux systems also work. - Modbus RTU (serial): a USB to RS-485 adapter (FTDI or CH340 based).

2. Install ModLens on Windows

1. Copy the ModLens folder anywhere, for example C:\Program Files\ModLens or your Desktop. There is nothing to install.
2. Double-click ModLens.exe.
3. If Windows shows "Windows protected your PC", click More info → Run anyway. This appears because the app is new and not yet code-signed.
4. If Windows Firewall asks, click Allow. It's only needed for the remote dashboard.
5. Optional: right-click ModLens.exe → Send to → Desktop (create shortcut).

First steps: see Using ModLens.

Keep ModLens running 24/7 (background mode)

• Closing the window does not stop ModLens. It keeps monitoring and logging in the system tray (the cyan icon next to the clock; click ^ if it's hidden).
• Double-click the tray icon (or start ModLens.exe again) to open the window.
• Right-click → Quit ModLens to really stop it.
• Start with Windows: right-click the tray icon → Start with Windows, or Settings → Run in the background. ModLens then starts minimized in the tray each time you log in, and the monitoring and logging you had running resume automatically.
• No sleep while working: while live monitoring runs, ModLens stops the PC from going to sleep (the screen can still turn off). On a laptop, keep it plugged in.
• Prefer that closing the window quits the app? Untick Settings → Keep running in the tray when I close the window.
• Logging even when nobody is logged in to Windows: create a task in Task Scheduler with trigger At startup, option Run whether user is logged on or not, action ModLens.exe --headless. The dashboard is then at http://127.0.0.1:8502. For a dedicated 24/7 logger, a Raspberry Pi is the simplest option (section 4).

Activate Pro: Settings → License → paste the key from your purchase email → Activate. To move the license to another PC, click Move license to another PC first.

Uninstall: delete the ModLens folder. To also remove your devices, tags and logs, delete %APPDATA%\ModLens.

3. Install ModLens Sim on Windows

1. Copy the ModLensSim folder anywhere.
2. Double-click ModLensSim.exe. - The first time, it creates an example simulation in C:\Users\<you>\ModLensSim\ (an AHU controller, a power meter fed by a CSV file, and a tank with live weather data). - The manager page opens in your browser at http://127.0.0.1:8090. - ModLens Sim runs in the system tray (purple icon next to the clock). It keeps simulating when you close the browser.
3. If Windows Firewall asks, click Allow so other computers (PLCs, BMS, ModLens on another PC) can reach the simulated devices.

Tray icon menu (right-click): | Item | What it does | |---|---| | Open ModLens Sim manager | Opens the manager page (double-click the icon does the same) | | Start with Windows | ModLens Sim starts in the tray at every Windows login, without opening the browser | | Quit ModLens Sim | Stops the simulated devices |

While ModLens Sim runs, the PC does not go to sleep, so the devices keep answering. Messages and errors are written to C:\Users\<you>\ModLensSim\modsim.log.

Simulated devices are available at: - Modbus TCP: this PC's IP address, port 5020, unit IDs 1, 2, 3 (example) - Modbus RTU: optional, see Settings

Run another simulation file: open a Command Prompt in the ModLens Sim folder and run:

ModLensSim.exe "D:\Projects\Site A\modsim.json"

Uninstall: delete the ModLensSim folder (and C:\Users\<you>\ModLensSim for your simulations).

4. Install on a Raspberry Pi (both apps)

4.1 Prepare the Pi

1. With Raspberry Pi Imager, flash Raspberry Pi OS Lite (64-bit). In the Imager settings: - enable SSH - set a username and password - set up Wi-Fi if you won't use a cable
2. Start the Pi and connect from your PC (Windows Terminal or PowerShell): ssh youruser@raspberrypi.local

4.2 Copy and install

From your PC, copy the package to the Pi:

scp modlens-linux.zip youruser@raspberrypi.local:~

Then on the Pi:

sudo apt install -y unzip
unzip modlens-linux.zip -d modlens
cd modlens
sudo bash tools/pi/install.sh --sim

The installer takes a few minutes. Both apps then start automatically at every boot and restart by themselves if they stop. At the end it prints the Pi's IP address and the links to open.

Log out and back in once (or reboot) so your user can use the USB to RS-485 adapter.

4.3 Open the dashboards

ModLens remote access (Pro). On the Pi:

/opt/modlens/.venv/bin/python /opt/modlens/run_modlens.py --activate YOUR-LICENSE-KEY
/opt/modlens/.venv/bin/python /opt/modlens/run_modlens.py --set-password a-strong-password
sudo systemctl restart modlens

Free version: open ModLens through an SSH tunnel from your PC:

ssh -L 8502:127.0.0.1:8502 youruser@raspberrypi.local

Then open http://127.0.0.1:8502 on your PC while that window stays open.

4.4 Managing the services

4.5 Update

Copy the new modlens-linux.zip to the Pi, then run unzip -o modlens-linux.zip -d modlens && cd modlens and the same install command again. Your devices, tags, logs and simulations are kept.

4.6 Uninstall

sudo systemctl disable --now modlens modsim
sudo rm /etc/systemd/system/modlens.service /etc/systemd/system/modsim.service
sudo rm -rf /opt/modlens

Your data stays in ~/ModLens and ~/modsim until you delete those folders.

A complete guide to building an on-site data logger (hardware list, RS-485 wiring, reliability tips) is in the Raspberry Pi data logger guide.

5. Using ModLens

Every screen has (?) buttons that explain each term, and errors come with a "What to try" checklist. The Help page has a Modbus glossary and troubleshooting.

Typical first session on site 1. Devices → + Add device. 2. No documentation? Scanner → Find unit IDs, then Find registers. 3. Know a value on the display? Find a value. 4. Explorer: click the green values to make tags. 5. Live & tags: set units/scale/alarms → Start live → Log to CSV.

Monitoring and logging restart automatically after a reboot or power cut, and old logs are deleted after 90 days (adjustable).

Free vs Pro | | Free | Pro | |---|---|---| | TCP + RTU, Explorer, writing, Find a value, tags, trends, alarms | ✅ | ✅ | | Register scan / Find a value range | up to 100 addresses | unlimited | | Live tags | 5 | unlimited | | Find devices and unit IDs, CSV logging, remote dashboard | | ✅ |

6. Managing the simulator (ModLens Sim)

Open the manager page: - Windows: http://127.0.0.1:8090 (opens by itself when you start ModLensSim.exe) - Raspberry Pi: http://<pi-ip>:8090

Everything you change in the manager is saved to the simulation's config file (modsim.json). When you click Save & apply, the simulated devices change immediately, without restarting.

6.1 The manager pages

A yellow bar appears when you have unsaved changes: click Save & apply, or Discard to cancel.

6.2 Create a simulated device, step by step

1. Devices & points → + Add device. Choose a unit ID (1–247) and a name, for example Unit 4 · Chiller 1.
2. Click + Point on that device and fill in: - Name: Chilled water supply temp - Table: Holding register (4x) · Address: 0 - Data type: int16 · Scale: 0.1 · Units: °C. You enter real values (6.7), and ModLens Sim sends them like a real device (67). - Behavior: Random drift, start 6.7, step 0.05, min 6, max 8
3. Add more points the same way (use Copy to duplicate one).
4. Click Save & apply. Your client can now read unit 4.

6.3 Value behaviors

Any behavior can add Noise ± for a more realistic signal.

Written values: when a client writes a holding register or coil (a setpoint, a command), ModLens Sim keeps the written value like a real device. Keep written value (s) = how long before returning to normal (0 = until restart). Untick Clients can write it to make a point read-only.

Addresses without a point don't exist: clients get "illegal data address", exactly like a real device. That makes ModLens Sim good for testing scanners.

6.4 Using real data

1. Data files → Upload files, or put files in the data folder next to modsim.json.
2. Data sources → + Add source:

3. Click Save & apply, then Preview data to see the available fields and their current values.
4. Edit a point → Behavior: From a data source → pick the source → click a field in the list (a CSV column name, or a JSON path like current.temperature_2m).

Useful tricks - Newest file in a folder: path data/exports/*.csv with Latest row. Drop a new export in the folder and ModLens Sim switches to it. - Replay a recorded day faster: CSV with a timestamp column, Replay rows, time column = timestamp, speed 60 (1 hour of data per minute). - Live link to another system: have it rewrite data/live.json every few seconds. ModLens Sim follows it and serves it over Modbus. - If a file or API fails, the last good value is kept and the error shows in Live values → Data sources.

6.5 Settings (TCP, RTU, password)

• Modbus TCP port: 5020 by default. Standard Modbus is 502; on a Raspberry Pi service, 502 also works.
• Modbus RTU: tick Enabled, set the serial port (Windows COM3, Pi /dev/ttyUSB0), baud rate, parity and stop bits. ModLens Sim then answers on the RS-485 bus as all the configured unit IDs.
• Manager password: recommended on shared networks. The browser asks for it (any user name).
• The password applies as soon as you save. Changes to ports and RTU apply after restarting ModLens Sim (Windows: close and reopen ModLensSim.exe; Pi: sudo systemctl restart modsim).

6.6 Backups, copies and editing by hand

• Every save keeps the previous version as modsim.json.bak next to the config.
• To reuse a simulation on another computer, copy the whole folder (modsim.json + data).
• Advanced users can edit modsim.json in any text editor. A point looks like this: json {"name": "Supply air temp", "address": 0, "type": "int16", "scale": 0.1, "units": "°C", "value": {"mode": "sine", "min": 12.5, "max": 16, "period": 900, "noise": 0.1}} Check a hand-edited file with ModLensSim.exe --check modsim.json (Pi: /opt/modlens/.venv/bin/python /opt/modlens/run_modsim.py --check ~/modsim/modsim.json).

7. Test both apps together

1. Start ModLens Sim (example simulation).
2. Start ModLens → Devices → + Add device: - Modbus TCP, IP 127.0.0.1 (same PC) or the simulator's IP, port 5020
3. Explorer: unit 1, holding, address 0, count 20 → Read. The green values are the simulated temperatures and pressure.
4. Find a value: enter the Return air temp shown in ModLens Sim's Live values page and watch ModLens find register 1, float32 ABCD.
5. In ModLens Sim, Force a high temperature and watch the alarm appear in ModLens's Live & tags.

8. Troubleshooting

9. Where files are stored