OP-BTS Python Script Manual

1. Overview

1.1 What is OP-BTS Python?

OP-BTS is the world’s first Python‑enabled meter optical probe that runs scripts directly on the device (Optical Probe for Meter Communication). It can work standalone without a PC or handheld. With an on‑board MCU and 16 MB of accessible storage, you can run your own Python scripts on the probe with a single button press.

As a meter‑reading device, OP-BTS together with scripting lets you write simple Python programs to:

• read meter data,
• display results on the device or send them over Bluetooth,
• and save data into the built‑in storage.

You upload scripts via the Windows application or over Bluetooth, then run them directly on the probe. The device supports transparent mode, automatic baud‑rate detection (Mode E / Mode C), Bluetooth 5.0, long battery life, and works with Android, iOS, Windows, macOS, and Linux.

OP-BTS Python is the Python scripting environment running on OP-BTS. It is based on the PikaPython core and provides a lightweight Python runtime within the resource limits of the device so you can use familiar syntax and libraries for meter reading and data processing.

1.2 What can you do with OP-BTS Python on OP-BTS?

• Interactive REPL: Connect over serial or Bluetooth and enter a Python interactive shell for step‑by‑step testing and debugging.
• Run downloaded scripts: Use the dedicated Windows application OpBtFileManager to compile and manage scripts, then run them directly on the probe.
• File‑system scripts: Store scripts in the device file system to implement offline meter reading, periodic data logging, and scheduled tasks.

1.3 How to use this manual

This manual covers getting started, basic syntax, standard libraries, device APIs, and practical examples.
For connecting to the device, uploading/running scripts, and the terminal workflow, see the OP File Manager User Manual.
For detailed terminal usage, see Using the Terminal (Interactive Mode).
Use the table of contents or example index to jump to the section you need.

2. Getting Started

2.1 Environment preparation

Before writing, downloading, or running scripts interactively, prepare the following hardware and software according to how you plan to use the device.

Hardware and connections

• OP-BTS device: Make sure your firmware supports OP-BTS Python (see the product manual or contact support).
• Connection options:
  • Optical‑head docking: Use a USB docking optical probe to connect to OP-BTS and configure the same serial parameters (baud rate, etc.) as the device.
  • Bluetooth: Pair OP-BTS with your PC or phone over Bluetooth, then use it for script download or interactive REPL over Bluetooth.

PC software (pick one)

• OpBtFileManager (recommended): Vendor‑provided Windows client for connecting to the device, uploading and running scripts, and viewing output. Supports direct optical‑head docking over USB, Bluetooth virtual COM port, Bluetooth SPP, and BLE connections.
• Serial/terminal tools: If you use a USB or virtual COM port, you can use any serial terminal such as PuTTY, SecureCRT, or other recommended tools. These are used to send commands, enter the Python REPL, and view output. Make sure you select the correct COM port and baud rate.

Mobile (optional)

• When using Bluetooth, you can use an Android or iOS app that supports SPP/BLE to communicate with OP-BTS, download scripts, or run them interactively (see the vendor’s mobile documentation for details).

2.2 Downloading and running scripts

Windows application OP-BTS PythonManager

• User manual: Full app guide (connect, upload, run, terminal workflow): OP File Manager User Manual.
• Introduction and download: Obtain the installer from the device documentation or the official website (download link).
• UI overview: After connecting to the device, select a script file, compile it, then click Download to write it to the device’s /py directory.
• Steps: Connect device → select script file → click Download → wait for completion.
• Progress and errors: The application shows download progress. If it fails, check the connection and serial/Bluetooth configuration.
• Script execution: You can run scripts directly from the application UI, or on the device via MENU → SCRIPTS, selecting and running the script.

Quick compile, upload and run

On the PC (OP File Manager):

1. Run the OP File Manager app
   ↓
2. Connect to the device
   ↓
3. Compile the .py file
   ↓
4. Upload the generated .py.o file to the device /py directory
   ↓
5. In the remote panel, select that .py.o file
   ↓
6. Click Run

On the device:

1. Press the left key (select) to show the menu
   ↓
2. Find Scripts, press the right key (OK) to enter the Python script list
   ↓
3. Select the .py.o file to run
   ↓
4. Press the right key (OK) to run

2.3 First script example

opbt.device.SetOutputMode(1)  # send output to Bluetooth
print('Hello OP-BTS Python!')

2.4 Interactive mode

Entering interactive mode

Use a serial or terminal tool to send commands to the device. Commands must be sent as a complete line, and each line must end with a line ending (\r\n or \n).

For firmware version > 4.68:

OP>2

That is, send the string OP>2 followed by carriage‑return and newline (\r\n).

For older firmware version < 4.68, send two commands:

OP>1
{"PythonRunMode":1}

Command behavior

After the above commands are sent, the device starts the Python interactive terminal and shows the prompt >>>.

Important: output port selection

• If you send OP>2\r\n from the optical‑head (serial) side, all subsequent REPL output will go to the optical‑head side.
• If you send OP>2\r\n from the Bluetooth side, all subsequent REPL output will go to the Bluetooth side.

Using the REPL and exiting

• At the >>> prompt, enter Python code and press Enter to execute.
• Enter exit() to leave interactive mode; on firmware versions > 4.60 this usually causes the device to reboot (for other versions, see the “Device not responding” section).

Multi-line code input

For multi-line code blocks (such as functions, loops, or classes), you must mark the beginning and end with #!pika:

#!pika
def hello():
    print("Hello, OP-BTS Python!")
hello()
#!pika

Notes for multi-line input:

• Use #!pika at the start and end to mark the code block
• The code block must have correct indentation
• The block must end with a line at the same indentation level as the outermost statement so the device knows the block is complete

Errors and exceptions

• If code contains errors, the device prints an error message in the terminal.
• To interrupt a long‑running script, hold the left key, then hold the right key until the red LED turns on; release the right key and keep holding the left key for more than 3 seconds to stop the current script (see the device manual for exact behavior).

Device not responding

• Method 1: Hold the left key, then press and hold the right key for more than 3 seconds to force the device to power off.
• Method 2: Press and hold the middle key for about 20 seconds to shut down the device.

For more detailed terminal usage, see Using the Terminal (Interactive Mode).

3. OP-BTS Python basics

OP-BTS Python supports a subset of standard Python 3 syntax.

3.1 Supported language features

• Data types: int, float, str, bool, list, dict, tuple, bytes
• Control flow: if, elif, else, while, for
• Functions: def, including default arguments, variable‑length arguments, and keyword arguments
• Classes: class with inheritance
• Module import: import, from ... import

3.2 Operators

Supported operators include +, -, *, /, ==, !=, >, <, >=, <=, %, **, //, &, |, and, or, not, in, etc.

3.3 Quick examples

# variables and types
a = 1
b = "hello"
c = [1, 2, 3]

# condition and loop
if a > 0:
    print(b)
for x in c:
    print(x)

4. Standard libraries

The device scripting environment includes these standard modules: time, struct, os, math, etc.
For detailed APIs, see the API documentation.

4.1 time module

• Purpose: delays and time operations.
• Inline example:

import time
time.sleep_ms(500)   # delay 500 ms

4.2 struct module

• Purpose: pack and unpack binary data.
• Inline example:

import struct
buf = struct.pack('hh', 1, 2)
a, b = struct.unpack('hh', buf)

4.3 os module

• Purpose: file and path operations (platform‑dependent).
• Inline example:

import os
p = os.path
p.join('dir', 'file.txt')

4.4 math module

• Purpose: math functions.
• Inline example:

import math
math.sqrt(2)
math.sin(0)

5. OP-BTS device API reference

Device scripts access hardware through the opbt module. See the OPBT device control API docs for full details.

5.1 Output mode

5.2 Serial port

5.3 Bluetooth serial port

5.4 LEDs and keys

5.5 Security unlock

Requires firmware 4.84 or later.

5.6 System and delay

5.7 LCD

For more parameters and color values, see ScriptDoc/cn/cn_module-opbt-device.md and the device manual.

6. Example index

This section is only an index; see each example document for full details.

6.1 OP-BTS device examples

• OP-BTS device examples: LED, serial port, LCD, keys, transparent transmission, IEC auto‑baud, security unlock, and combined usage.

6.2 OP-BTS Python built‑in feature examples

• Basic data types
• Data structures
• String operations
• Function definitions
• Classes and objects
• Advanced class usage
• Exception handling
• Control flow
• File operations
• Module imports
• Type checking
• Other built‑ins

6.3 Standard‑library examples

• time module examples
• struct module examples
• os module examples
• math module examples

7. Security unlock examples

Requires firmware 4.84 or later.

When the device has security enabled (SecurityEnable), scripts can call CheckUnlock() to verify unlock status before sensitive operations; if not unlocked, the LCD password input screen is shown.

import opbt
if opbt.device.CheckUnlock() != 1:
    print("Unlock canceled")
else:
    print("Unlocked, proceed")

To query whether the device is currently unlocked only (no UI):

import opbt
if opbt.device.IsUnlocked():
    print("Already unlocked")
else:
    print("Locked")

8. Debugging and troubleshooting

• Memory monitoring: Use MemChecker() and its max() / now() methods to observe memory usage.
• Common issues: Check that imported modules are supported on this device; verify serial/Bluetooth connections; ensure the output mode matches the port you are using.
• Debugging tips: Start with print() or LCD output for key variables; in interactive mode, run commands step by step to isolate problems.

9. Appendix

9.1 Quick API reference

See the tables in section 5 and the detailed device API documentation.

9.2 LCD color values

9.3 LED bit‑mask reference

©2007-2024 TESPRO CORPORATION. ALL RIGHTS RESERVED.

English | 中文 |