kymocore 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
kymocore/__init__.py ADDED
@@ -0,0 +1,54 @@
1
+ """Send measurements from Python to KymoStudio (Kymotrace binary protocol v6.2)."""
2
+ import time
3
+
4
+ from . import transport
5
+ from .protocol import crc8, frame
6
+
7
+ __all__ = ['Sender', 'frame', 'crc8', 'transport']
8
+ __version__ = '0.1.0'
9
+
10
+
11
+ class Sender:
12
+ """Stamps each value with the time since the sender started and writes one frame.
13
+
14
+ ``timestamps``: 'us' (wraps after 71.6 min), 'ms' (wraps after 49.7 days) or None.
15
+ Use one unit per connection; KymoStudio treats a change as a clock restart.
16
+ """
17
+
18
+ def __init__(self, sink, *, timestamps: str = 'us', crc: bool = False):
19
+ if timestamps not in ('us', 'ms', None):
20
+ raise ValueError("timestamps must be 'us', 'ms' or None")
21
+ self._sink, self._timestamps, self._crc = sink, timestamps, crc
22
+ self._start = time.monotonic_ns()
23
+
24
+ @classmethod
25
+ def udp(cls, host, port, **kwargs):
26
+ return cls(transport.Udp(host, port), **kwargs)
27
+
28
+ @classmethod
29
+ def tcp_server(cls, port, host='0.0.0.0', **kwargs):
30
+ return cls(transport.TcpServer(port, host), **kwargs)
31
+
32
+ @classmethod
33
+ def serial(cls, port, baudrate=115200, **kwargs):
34
+ return cls(transport.Serial(port, baudrate), **kwargs)
35
+
36
+ @classmethod
37
+ def mqtt(cls, host, topic, port=1883, *, qos=0, username=None, password=None, client_id='', **kwargs):
38
+ return cls(transport.Mqtt(host, topic, port, qos=qos, username=username,
39
+ password=password, client_id=client_id), **kwargs)
40
+
41
+ def send(self, id: int, y: float, *, x: float = None, z: float = None):
42
+ t = None
43
+ if self._timestamps:
44
+ t = (time.monotonic_ns() - self._start) // (1000 if self._timestamps == 'us' else 1_000_000)
45
+ self._sink.write(frame(id, y, x, z, t, us=self._timestamps == 'us', crc=self._crc))
46
+
47
+ def close(self):
48
+ self._sink.close()
49
+
50
+ def __enter__(self):
51
+ return self
52
+
53
+ def __exit__(self, *exc):
54
+ self.close()
kymocore/protocol.py ADDED
@@ -0,0 +1,33 @@
1
+ """Kymotrace compact binary protocol v6.2 data frames (KymoCore PROTOCOL.md)."""
2
+ import math
3
+ import struct
4
+
5
+ SYNC = b'\xa5\x5a'
6
+
7
+
8
+ def crc8(data: bytes) -> int:
9
+ """CRC-8/ATM: polynomial 0x07, init 0, no reflection, no xor-out."""
10
+ crc = 0
11
+ for byte in data:
12
+ crc ^= byte
13
+ for _ in range(8):
14
+ crc = ((crc << 1) ^ 0x07) & 0xFF if crc & 0x80 else (crc << 1) & 0xFF
15
+ return crc
16
+
17
+
18
+ def frame(id: int, y: float, x: float = None, z: float = None, t: int = None, *,
19
+ us: bool = False, crc: bool = False) -> bytes:
20
+ """One data frame. ``t`` counts ms (or µs with ``us``) since the sender started."""
21
+ if not 0 <= id <= 255:
22
+ raise ValueError(f'channel id {id} outside 0..255')
23
+ values = [v for v in (x, y, z) if v is not None]
24
+ if not all(math.isfinite(v) for v in values):
25
+ raise ValueError('NaN and infinity cannot be sent')
26
+ if us and t is None:
27
+ raise ValueError('microseconds need a timestamp')
28
+ descriptor = (0x40 | (0x08 if x is not None else 0) | (0x04 if z is not None else 0)
29
+ | (0x02 if t is not None else 0) | (0x10 if us else 0) | (0 if crc else 0x01))
30
+ body = bytes([descriptor, id]) + struct.pack(f'<{len(values)}f', *values)
31
+ if t is not None:
32
+ body += struct.pack('<I', t & 0xFFFFFFFF) # wraps; KymoStudio continues the axis
33
+ return SYNC + body + bytes([crc8(body) if crc else 0])
kymocore/transport.py ADDED
@@ -0,0 +1,87 @@
1
+ """Byte sinks for KymoStudio's sources. Each has write(data) and close()."""
2
+ import socket
3
+
4
+
5
+ class Udp:
6
+ """KymoStudio's UDP source listens; datagrams go to its address."""
7
+
8
+ def __init__(self, host: str, port: int):
9
+ self._address = (host, port)
10
+ self._sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
11
+
12
+ def write(self, data: bytes):
13
+ self._sock.sendto(data, self._address)
14
+
15
+ def close(self):
16
+ self._sock.close()
17
+
18
+
19
+ class TcpServer:
20
+ """KymoStudio's Telnet/TCP source connects like to a device, so this side listens.
21
+
22
+ Frames go to every connected client; without one they are dropped, as on a device.
23
+ """
24
+
25
+ def __init__(self, port: int, host: str = '0.0.0.0'):
26
+ self._server = socket.create_server((host, port))
27
+ self._server.setblocking(False)
28
+ self._clients = []
29
+
30
+ def write(self, data: bytes):
31
+ try:
32
+ while True:
33
+ client, _ = self._server.accept()
34
+ client.setblocking(True)
35
+ self._clients.append(client)
36
+ except BlockingIOError:
37
+ pass
38
+ for client in self._clients[:]:
39
+ try:
40
+ client.sendall(data)
41
+ except OSError:
42
+ client.close()
43
+ self._clients.remove(client)
44
+
45
+ def close(self):
46
+ for client in self._clients:
47
+ client.close()
48
+ self._server.close()
49
+
50
+
51
+ class Serial:
52
+ """Serial port or USB CDC; needs ``pip install kymocore[serial]``."""
53
+
54
+ def __init__(self, port: str, baudrate: int = 115200):
55
+ import serial
56
+ self._port = serial.Serial(port, baudrate)
57
+
58
+ def write(self, data: bytes):
59
+ self._port.write(data)
60
+
61
+ def close(self):
62
+ self._port.close()
63
+
64
+
65
+ class Mqtt:
66
+ """Publishes frames to a topic of KymoStudio's MQTT source (its receive topics).
67
+
68
+ Needs ``pip install kymocore[mqtt]``. One message per frame; KymoStudio also
69
+ accepts several concatenated frames in one payload.
70
+ """
71
+
72
+ def __init__(self, host: str, topic: str, port: int = 1883, *, qos: int = 0,
73
+ username: str = None, password: str = None, client_id: str = ''):
74
+ import paho.mqtt.client as mqtt
75
+ self._topic, self._qos = topic, qos
76
+ self._client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=client_id)
77
+ if username:
78
+ self._client.username_pw_set(username, password)
79
+ self._client.connect(host, port)
80
+ self._client.loop_start() # paho reconnects by itself while the loop runs
81
+
82
+ def write(self, data: bytes):
83
+ self._client.publish(self._topic, data, qos=self._qos)
84
+
85
+ def close(self):
86
+ self._client.loop_stop()
87
+ self._client.disconnect()
@@ -0,0 +1,167 @@
1
+ Metadata-Version: 2.4
2
+ Name: kymocore
3
+ Version: 0.1.0
4
+ Summary: Send measurements from Python to KymoStudio (Kymotrace binary protocol)
5
+ Author: Christof Seidel
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://kymotrace.de
8
+ Project-URL: Source, https://github.com/KymoTrace/kymocore-python
9
+ Project-URL: Issues, https://github.com/KymoTrace/kymocore-python/issues
10
+ Project-URL: Protocol, https://github.com/KymoTrace/kymocore/blob/main/PROTOCOL.md
11
+ Keywords: kymotrace,kymostudio,telemetry,plotting,mqtt,serial
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Topic :: Scientific/Engineering :: Visualization
18
+ Classifier: Topic :: System :: Hardware
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Provides-Extra: serial
23
+ Requires-Dist: pyserial>=3.5; extra == "serial"
24
+ Provides-Extra: mqtt
25
+ Requires-Dist: paho-mqtt>=2.0; extra == "mqtt"
26
+ Provides-Extra: test
27
+ Requires-Dist: pytest; extra == "test"
28
+ Requires-Dist: pyserial>=3.5; extra == "test"
29
+ Requires-Dist: paho-mqtt>=2.0; extra == "test"
30
+ Dynamic: license-file
31
+
32
+ <p align="center">
33
+ <a href="https://github.com/KymoTrace/kymocore-python/blob/main/README.md"><img alt="English" src="https://img.shields.io/badge/%F0%9F%8C%90-English-15123A"></a>
34
+ <a href="https://github.com/KymoTrace/kymocore-python/blob/main/README.de.md"><img alt="Deutsch" src="https://img.shields.io/badge/%F0%9F%8C%90-Deutsch-A78BFA"></a>
35
+ </p>
36
+
37
+ <p align="center">
38
+ <picture>
39
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/KymoTrace/kymocore/main/docs/images/kymotrace-logo-dark.svg">
40
+ <img src="https://raw.githubusercontent.com/KymoTrace/kymocore/main/docs/images/kymotrace-logo-light.svg" alt="Kymotrace – Embedded Telemetry" width="480">
41
+ </picture>
42
+ </p>
43
+
44
+ <h3 align="center">kymocore for Python · Measurements from your script, live on screen</h3>
45
+
46
+ <p align="center">
47
+ Pure Python sender for the Kymotrace protocol – the PC counterpart of <b>KymoCore</b>.
48
+ </p>
49
+
50
+ <p align="center">
51
+ <img alt="Version 0.1.0" src="https://img.shields.io/badge/version-0.1.0-7C5CFF">
52
+ <img alt="License MIT" src="https://img.shields.io/badge/License-MIT-15123A">
53
+ <img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-A78BFA">
54
+ <img alt="Transports" src="https://img.shields.io/badge/UDP%20%C2%B7%20TCP%20%C2%B7%20Serial%20%C2%B7%20MQTT-FDE047">
55
+ </p>
56
+
57
+ ---
58
+
59
+ ## What is it about?
60
+
61
+ Not every signal comes from a microcontroller. A Raspberry Pi reads sensors,
62
+ a test bench script drives a power supply, a simulation computes a plant model.
63
+ Printing those values or writing CSV files means looking at them **afterwards**.
64
+
65
+ **kymocore** sends them to [KymoStudio](https://kymotrace.de/download.html) while
66
+ they happen, with the same compact binary frames (**9 to 21 bytes**) that the
67
+ [KymoCore](https://github.com/KymoTrace/kymocore) firmware library uses. Firmware
68
+ and PC script appear side by side in one KymoStudio workbench: as curves,
69
+ XY traces or in 3D.
70
+
71
+ <p align="center">
72
+ <img src="https://raw.githubusercontent.com/KymoTrace/kymocore/main/docs/images/kymostudio-workbench.png" alt="KymoStudio showing measurements live as a time series and an XY chart" width="900">
73
+ <br><sub>Live data in KymoStudio: three signals over time, two as XY traces.</sub>
74
+ </p>
75
+
76
+ ## What kymocore can do
77
+
78
+ | | |
79
+ |---|---|
80
+ | **One call per value** | `send(channel, value)`, optionally with `x=` and `z=` for XY and XYZ charts. Up to 256 channels. |
81
+ | **Timestamps included** | Each value carries the time since the sender started, in microseconds or milliseconds, from a monotonic clock. |
82
+ | **Four transports** | UDP, TCP, serial/USB and MQTT. KymoStudio's existing sources receive them unchanged. |
83
+ | **No dependencies** | The core uses only the standard library. `pyserial` and `paho-mqtt` are optional extras. |
84
+ | **Same protocol as the firmware** | Tested against the golden vectors of [PROTOCOL.md](https://github.com/KymoTrace/kymocore/blob/main/PROTOCOL.md) v6.2, optional CRC-8 checksum. |
85
+ | **Raw frames too** | `frame()` returns the bytes for a transport of your own. |
86
+
87
+ ## What it is used for
88
+
89
+ - **Raspberry Pi and single-board computers:** plot sensor values read via I²C, SPI or GPIO live.
90
+ - **Test benches and HIL setups:** show the script's setpoints next to the measurements of the device under test.
91
+ - **Simulations:** watch a plant model or controller simulation run, with the same charts as on real hardware.
92
+ - **Data from other programs:** forward values from instruments, logs or APIs to KymoStudio.
93
+
94
+ ## Quick start
95
+
96
+ ```bash
97
+ pip install kymocore # UDP and TCP
98
+ pip install kymocore[serial] # + serial / USB CDC (pyserial)
99
+ pip install kymocore[mqtt] # + MQTT (paho-mqtt)
100
+ ```
101
+
102
+ ### Complete example
103
+
104
+ The following script sends a sine wave on channel 0 and a cosine with an X
105
+ coordinate on channel 1, every 10 ms for ten seconds.
106
+
107
+ ```python
108
+ import math
109
+ import time
110
+
111
+ from kymocore import Sender
112
+
113
+ with Sender.udp('127.0.0.1', 5025) as sender:
114
+ for i in range(1000):
115
+ sender.send(0, math.sin(i / 20)) # channel 0, value
116
+ sender.send(1, math.cos(i / 20), x=i) # channel 1, XY point
117
+ time.sleep(.01)
118
+ ```
119
+
120
+ In KymoStudio, add a **UDP** source on port 5025, start it and assign
121
+ channel 0 to a chart.
122
+
123
+ ## Transports
124
+
125
+ | Transport | Call | KymoStudio source |
126
+ |---|---|---|
127
+ | UDP | `Sender.udp(host, port)` | UDP, listens on `port` |
128
+ | TCP | `Sender.tcp_server(port)` | Telnet/TCP, connects to this machine and `port` |
129
+ | Serial | `Sender.serial('COM4', 115200)` | Serial, same baud rate |
130
+ | MQTT | `Sender.mqtt(broker, topic)` | MQTT, `topic` among its receive topics |
131
+
132
+ KymoStudio connects to a TCP device, so `tcp_server` listens and sends to every
133
+ connected client. Values sent while no client is connected are dropped, as on a
134
+ device. MQTT publishes one message per value.
135
+
136
+ ## Options
137
+
138
+ | Option | Default | Meaning |
139
+ |---|---|---|
140
+ | `timestamps='us'` | yes | Microseconds; wraps after 71.6 minutes, KymoStudio continues the time axis |
141
+ | `timestamps='ms'` | | Milliseconds; wraps after 49.7 days |
142
+ | `timestamps=None` | | No timestamp; KymoStudio stamps on arrival |
143
+ | `crc=True` | off | Adds the CRC-8/ATM checksum to every frame |
144
+
145
+ Channel IDs outside 0–255 and NaN or infinite values raise `ValueError`.
146
+ Microsecond timestamps need KymoStudio 2.5 or newer.
147
+
148
+ ## Part of Kymotrace
149
+
150
+ | Project | Role |
151
+ |---|---|
152
+ | [KymoCore](https://github.com/KymoTrace/kymocore) | firmware library: capture and send measurements on the microcontroller |
153
+ | **[kymocore for Python](https://github.com/KymoTrace/kymocore-python)** | this package: send measurements from Python |
154
+ | [KymoProbe](https://github.com/KymoTrace/kymoprobe) | firmware and hardware examples for ESP32, Arduino and STM32 |
155
+ | [KymoStudio](https://kymotrace.de/download.html) | desktop app: receive, display, analyse, export |
156
+
157
+ ## Documentation
158
+
159
+ - **[Protocol](https://github.com/KymoTrace/kymocore/blob/main/PROTOCOL.md):** byte layout, CRC, example frames
160
+ - **[Website](https://kymotrace.de):** KymoStudio download, guides and features
161
+
162
+ ## License
163
+
164
+ Copyright (c) 2026 Christof Seidel. kymocore for Python is licensed under the
165
+ [MIT license](https://github.com/KymoTrace/kymocore-python/blob/main/LICENSE):
166
+ free for any use, including commercial projects, without disclosing your own
167
+ source code.
@@ -0,0 +1,8 @@
1
+ kymocore/__init__.py,sha256=2GUHz2SWk67HZDbOTvN42Q4qlUSoOJDZOzRYTLlPmX4,1961
2
+ kymocore/protocol.py,sha256=G4EC-8bzpSyW4wTDTJQbhBFGbbcMHSIULtdYy5m6szk,1407
3
+ kymocore/transport.py,sha256=jmoFWLH_gVrUFqSlWCZYAWM-_RytFZ1Y5j6PSG1OlfA,2732
4
+ kymocore-0.1.0.dist-info/licenses/LICENSE,sha256=eW02LnXYVDva8274nDLLormTmQK7Q0BN6m7rsoPjCkE,1072
5
+ kymocore-0.1.0.dist-info/METADATA,sha256=UaK1ywkxoTZ5qA9YEeRZ9U7cOhUpPJy6KNN1H_3WWoc,7519
6
+ kymocore-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
7
+ kymocore-0.1.0.dist-info/top_level.txt,sha256=v5xrC33mrK7a_yCVWKPaSKhejN2tk6skaKogNXgrX3g,9
8
+ kymocore-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Christof Seidel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ kymocore