This release is a pre-release and may not be stable for production use.
naneos-devices
Python package for the naneos particle solutions measurement devices (Partector 1, Partector 2, Partector 2 Pro). It connects to the devices over USB and Bluetooth Low Energy, delivers the measurements as pandas DataFrames, and can upload them to the naneos IoT service.
Installation
Python 3.11 to 3.14 is supported.
pip install naneos-devices
The device manager
NaneosDeviceManager is all most applications need. It runs as a background thread, finds and
connects every Partector on USB and Bluetooth, gathers their data in snapshots and, if you
want, uploads them to the naneos IoT service.
- 🔌 USB and BLE, each can be switched on and off, also while running
- 🎯 Optional BLE allow-list (
ble_serial_numbers) and link limit (ble_max_links, default 7) - ⏱️ Gathering interval of 10 to 600 s
- 📤 Optional upload to the naneos IoT service (always at 1 Hz)
- 📦 Snapshots as
dict[int, pandas.DataFrame]on a queue, for your own processing - ⚡ Live data: every data point on a queue the moment it arrives
- 💬 Send commands to a device, read its answers and set its data rate, the same way on USB and BLE
Quick start: upload everything in reach
Example: examples/quick_start.py
import time
from naneos import NaneosDeviceManager, enable_console_logging
from naneos.logger import LEVEL_INFO
enable_console_logging(LEVEL_INFO) # the library is silent by default
manager = NaneosDeviceManager(
use_serial=True,
use_ble=True,
upload_active=True,
gathering_interval_seconds=30, # clamped to [10, 600]
ble_serial_numbers=None, # or e.g. [8617, 8764] to link only to your own devices
)
manager.start()
try:
while True:
time.sleep(manager.seconds_until_next_snapshot + 1)
for device in manager.get_devices():
print(device) # e.g. <Partector2 SN8617 P2 serial>
except KeyboardInterrupt:
pass
manager.stop()
manager.join()
Process the data yourself
Example: examples/queue_handoff.py
Register a queue and every snapshot is put on it, with or without the upload:
import queue
import time
from naneos import NaneosDeviceManager
snapshots: queue.Queue = queue.Queue()
manager = NaneosDeviceManager(upload_active=False, gathering_interval_seconds=15)
manager.register_output_queue(snapshots)
manager.start()
try:
while True:
time.sleep(manager.seconds_until_next_snapshot + 1)
while not snapshots.empty():
snapshot = snapshots.get() # dict[int, pandas.DataFrame], keyed by serial number
for serial_number, df in snapshot.items():
print(f"SN{serial_number}: {len(df)} rows, mean LDSA {df['ldsa'].mean():.1f}")
except KeyboardInterrupt:
pass
manager.stop()
manager.join()
The frames are indexed by the unix timestamp in milliseconds; the columns are the fields of
NaneosDeviceDataPoint (ldsa, particle_number_concentration,
average_particle_diameter, device_status, ...).
Live data
Example: examples/live_data.py
Snapshots arrive every 10 s at best. For a live view, register a live queue: it receives every
data point the moment it arrives, as a NaneosDeviceDataPoint, next to the snapshots and the upload.
import queue
from naneos import NaneosDeviceManager
live: queue.Queue = queue.Queue(maxsize=10_000) # bounded: a full queue drops its oldest point
manager = NaneosDeviceManager(upload_active=False)
manager.register_live_queue(live)
manager.start()
while True:
point = live.get()
print(point.serial_number, point.connection_type, point.unix_timestamp, point.ldsa)
examples/live_plot.py uses this to plot the diffusion current of a device on USB.
The points come at the rate of the device (1 Hz, or what you set over USB). A device that is connected over USB and BLE delivers its USB points only.
Change it while it runs
Example: examples/runtime_controls.py
manager.use_serial = False # USB devices off / on
manager.use_ble = True # BLE devices off / on
manager.upload_active = False # keep gathering, stop uploading
manager.gathering_interval_seconds = 45 # 10 to 600 s
print(manager.seconds_until_next_snapshot, manager.pending_upload_count)
When the internet is down
The upload runs on a thread of its own, so a missing connection never holds up the gathering.
Until it works again the manager keeps the snapshots in RAM, up to upload_buffer_mb
(NaneosDeviceManager(upload_buffer_mb=100), the default): about 4 days for a P2 and a P2 Pro
at 1 Hz, see the Raspberry Pi guide
for more. When the connection is back the data is sent oldest first, in requests of up to
10 minutes (and about 2000 rows) each, and lands at its own time on the server. When the buffer is full the oldest data is
dropped, and everything is lost when the process ends: nothing is written to disk.
manager.pending_upload_count (snapshots), pending_upload_seconds and pending_upload_bytes
show what is waiting.
Talk to a device: commands and data rate
Example: examples/device_commands.py
Every connected device is available as a handle with the same API over USB and BLE. A device that is reachable both ways is handed out with its USB connection.
from naneos import NotSupportedError
for device in manager.get_devices():
print(device.serial_number, device.device_type, device.connection_type)
print(device.query("f?")) # a command with an answer -> ["422"]
device.write("A0002!") # a command without an answer
try:
device.set_sample_rate(10) # 0 (off), 1, 10 or 100 Hz, None for the device default
except NotSupportedError:
pass # over BLE the rate is fixed at 1 Hz, it can only be changed over USB
# or address a device by its serial number
manager.query(8617, "name?")
manager.write(8617, "A0002!")
manager.set_sample_rate(8617, 100)
# the two diagnostics of a P2 (firmware 418 or newer), over USB and BLE alike
curve = manager.read_ui_curve(8617) # electrometer current over corona voltage, 100 points
form = manager.read_pulse_form(8617) # one charging pulse, 200 samples
# the manager reads and uploads both of every device once an hour: diagnostics_interval_hours
# or set the rate of every USB device, now and for the ones plugged in later
manager.sample_rate_hz = 10 # also NaneosDeviceManager(sample_rate_hz=10)
- An unknown serial number raises
KeyError, a lost deviceConnectionError, a missing answerTimeoutError. Calls are safe from any thread. - Your queue receives the data at the rate you set. The upload to naneos is always limited to 1 Hz. 100 Hz is meant for tests.
- A rate set on one device is not remembered: a device that reconnects gets
manager.sample_rate_hz. - A Partector 2 Pro on USB starts in size distribution mode, where it sets its own pace
(
sample_rate_hzisNone); a rate switches it to the plain P2 line. See the documentation for the details.
Logging
The library logs to loggers below naneos and prints nothing by default:
from naneos.logger import LEVEL_INFO, enable_console_logging, enable_file_logging
enable_console_logging(LEVEL_INFO) # coloured output on stderr
enable_file_logging("logs/", LEVEL_INFO) # appends to logs/naneos-devices.log
More examples
| Example | What it shows |
|---|---|
quick_start.py |
upload everything in reach |
queue_handoff.py |
process the snapshots yourself |
live_data.py |
every data point the moment it arrives |
live_multi_device.py |
several USB devices at 10 Hz on the live queue |
live_plot.py |
live plot of the diffusion current of a device on USB (needs pip install matplotlib) |
runtime_controls.py |
switch transports, upload and interval while running |
device_commands.py |
commands, answers and the data rate |
diagnostics.py |
the UI curve and the pulse form of every device, on request and on the hourly schedule |
send_commands.py |
send a file of commands to one device |
serial_device.py |
one USB device without the manager |
download_iotweb.py |
read your data back from the naneos IoT service (needs pip install "naneos-devices[download]") |
Documentation
The documentation covers the rest:
- Raspberry Pi as an always-on uploader. Tested on a Raspberry Pi Zero 2 W and a Pi Zero W (1st generation). The Zero W works too, but its old hardware makes installation and every boot really slow.
- Devices, commands and the Partector 2 Pro modes
- Migrating from 1.x to 2.0
- Development: tests, protobuf, releases
- API reference
License
This repository is licensed under the MIT License.
Contact
- Mario Huegi, mario.huegi@naneos.ch, GitHub
- Issues and suggestions: issue tracker
1 maintainer
Release files for naneos-devices 2.0.9rc2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| naneos_devices-2.0.9rc2.tar.gz | 299.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| naneos_devices-2.0.9rc2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 403.6 kB
Release files / naneos_devices-2.0.9rc2.tar.gz
| Download URL | naneos_devices-2.0.9rc2.tar.gz |
|---|---|
| Size | 299.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
64f1e8a7bc0f8be3e48811c36663479b10627a721be4503713ddb06f465c3763
|
|
BLAKE2b-256 checksum How to use checksums |
c647ec06a92166c4823faa581db22a2a9cc38f91fb5afd804ae2b3e5badc6532
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / naneos_devices-2.0.9rc2-py3-none-any.whl
| Download URL | naneos_devices-2.0.9rc2-py3-none-any.whl |
|---|---|
| Size | 104.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3787c8a6ca0dedd4b67cf4a1455ced658ef00c70660ca489370af686064be081
|
|
BLAKE2b-256 checksum How to use checksums |
1b9d7c599f6000a214352d6f437f06343e249a21059882b7226f87e6af08d142
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
