Menarini-read

Description

The Menarini V-Sight blood-analysis machine has two modes of communication: With and without handshake.

Protocols

Without handshake

The device sends STX, followed by data and an EOF.

Menarini		PC
STX	->
Data	->
EOF	->

With handshake

The device sends an ENQ and then waits for an ACK. After receiving an ACK, it sends Data, EOT, ETX and then waits for ACK again.

Menarini		PC
ENQ	->
	<-	ACK
Data	->
EOT	->
ETX	->
	<-	ACK

Controls

ASCII	Description	Cntrl	Value
STX	Start of Text	^B	0x02
ETX	End of Text	^C	0x03
EOT	End Of Transmission	^D	0x04
ENQ	Enquiry	^E	0x05
ACK	Acknowledge	^F	0x06
EOF	End Of File	^Z	0x1A

Data

The actual data is a long string that consists mostly of ASCII digits. Like '062820212009'. It took quite a bit of reverse engineering to figure out what it all means. As far as I can tell, this is what is in the data;

Pos	Length	Data
0	1	'A'
10	12	date
22	70	data
98	3	species
109	24	lines
149	2304	graphs

Including padding it's 2453 bytes.
The data consists of;

Data	Length
WBC	4
Lymph#	4
Mon#	4
Gran#	4
Lymph%	3
Mon%	3
Gran%	3
RBC	4
HGB	3
MCHC	4
MCV	4
MCH	4
RDW	3
HCT	3
PLT	4
MPV	3
PDW	3
PCT	3
padding	4
Eos%	3

HGB, MCHC and MCH are in grams instead of mols. The software converts these to mols.
The data is followed by three graphs with some vertical lines.

Software

he device only uses TDX, RXD and GND, so there is no use in using modem control lines or RTS - CTS flow control. The device might support XON - XOFF, but there is no indication that it does.
I wrote some serial port software before, so I just modified what I had to retrieve data from the device;
On reception of a STX or an ENQ, the software generates a filename containing date and time. The '-n' option can be used to set the filename prefix. Without the prefix the TTY name is used. The time is followed by milliseconds and the filename has the '.txt' extension: Prefix-YYYYMMDD-hhmmss-ms.txt, E.G.: ttyS1-20210714-132727-123.txt. The file is closed on the reception of an EOF or an ETX.
The files are saved in a directory set with the '-p' option. If it can't open files in this dir and an alternative destination directory is set with the '-a' option, it will save in this directory instead. When this happens, it will send an email to the address set with the '-m' option, provided this option is set.
The program saves a Pid file in the directory set with '-r'. The program can be killed with a SIGTERM; kill -TERM `cat Pid_File`.
'-l' enables logging and sets the log-file name and directory.

Configuration file

The configuration file, '/etc/menarini/vsight.conf', contains minimum and maximum blood values per species / type of animal. Each section starts with the animal type in brackets. EG: '[Dog]'. Valid types are Dog, Cat, Horse, Rat, Mouse, Rabbit, Monkey, Cow, Pig, Buffalo, Camel, Sheep and Goat. This is followed by blood value, minimum and maximum, One per line. EG:

Val	Min	Max
WBC	6.0	17.0
Lymph#	0.8	5.1
Mon#	0.0	1.8

You need all three on each line. The value '0.0' is ignored (not considered a minimum or maximum). Entries are case insensitive and can have any order.
Note: hash ('#') can be part of a variable name, so hash can only be a remark on the first position of a line;

# Right remark.
Wrong # remark.

The software will insert a 'L' in the output when a value is too low and a 'H' when it is too high. The '-N' option lists the minumum and maximum values in the output.

Other output

Instead of plain text, the software can also generate HTML and images.
With the '-U' the output text is UTF-8 instead of US-ASCII.
With the '-G' option the software will produce graphs. These are Platelet, Haemoglobin and White blood cell histogram.
The '-H' option produces UTF-8 HTML and graphs. A '-t' uses tables.
And the '-R' option saves the data as is. This 'raw' file can be converted to one of the the above formats with the '-f' option.

Options

Examples

menar-read -b 9600 -d /dev/ttyS1 -l mylogs/log -p mydest/ -P n -r mypid/: Use device /dev/ttyS1 at 9600 bps. Put logfile in mylogs/log and output files in directory mydest. Use 7-bits no parity and put pidfile in directory mypid.
menar-read -f ttyS1-20181224-135557-123.raw -H -t: Convert raw file ttyS1-20181224-135557-123.raw into HTML file with table.
Note: This also generates graphs.

Download and install

Download source: menar.tar.gz
Extract with: tar xvfz menar.tar.gz
Compile with: cc -O2 -Wall -o menar-read menar-read.c
Copy menar-read to /usr/local/bin/
Copy vsight.conf to /etc/menarini/
Copy menar-read.1 to /usr/local/share/man/man1/
Copy vsight.conf.5 to /usr/local/share/man/man5/
Gzip man page: gzip menar-read.1
Gzip config file man page: gzip vsight.conf.5

Systemd

Starting the program from systemd may lead to the program running at 100% CPU. This is caused by systemd closing stdin.
Using the '-i' option (ignore stdin) fixes this.

Version

Version: 2021-08-27 13:10:09 GMT