pyLabManager

Introduction

labManager is an independent, open-source scalabale lab managment software, built around RS-232 communication with industry-standard equipment. Development is currently in progress for Just Biotherapudic to be used for lab automation.

Unknowns / Further Research

• Operator ID - Lab insturments post a value labeled 'Operator ID' when communicating a result or recalling result. There is a potential this field can be used to further improve automation.
• Two-Way Communication - Unfortunatly, all communication between the OSMO 2020 is currently one way. A user initilizes the sample, then software handles the reception of the data. In multiple intrument manuals, there is mention of two-way communication, however this functionality has not been tested.
• Threading Data Flow - As the niche of this software beccomes further enumerated, the potential need for threading arises, and could potentially be explored as another avenue. It is unclear weather or not threading is nessissary at this time.
• Enumerating OSMO Communcation Cases - Not all possible messages have been recorded and identified for the OSMO 2020. Thus, there are many holes in OSMO2020Manager.py, corresponding to the unknowns.
  • Power on
  • Save configuration
  • Recall Results
  • Report Results

Documentation

hardwareManager.py

Description

• hardwareManager is responsible for managing all of the hardware objects and their states. The hardwareManager is a singleton, and maintains a list of all Inturment Managers. The hardware manager is the first line of communication between a result generated by the user, and the physical devices.

• The manager is designed with a focus on slowly de-escalating abstractions, and providiing a high ceiling to scalable development. The hardwareManager does not have a hard limit of Inturment Managers.

Methods / Varibles assoiaced with the Hardware Manager:

• List of all Inturment Managers
• A method to find an insturment by serial number
• A method to find all insturment of a model
• A method to regiser a insturmentManager

OSMO2020Manager.py

Description

• The OSMO 2020 manager is a proof-of-concept for instument managers. It is the first non-singleton object. The creation of instument managers is highly customizable, they can be created from a file configuration, created in small quantitys in main.py, or remotely-created from ignition or a webserver.

Methods / Varibles assoiaced with the OSMO2020 Manager:

• A method to parse data in the input buffer in 'recall data' format
• A method to parse data in the input buffer in 'result reporting' format
• A method to block for N bytes of data
• A method to block for self-identify (I.E Determine what message was sent based on only the message) [UNWRITTEN]
  • The self-identify feature was ruled unnessissary after getting a better idea of the commands. There are only ~2 commands that give the serial number of the insturment. It is safe to assume the sysadmin will know the serial number of the machine during the registration process.
• A method to decode a passed message [UNWRITTEN]
• A First-In-First-Out Stack
• Flags to represent the current state of the insturment

main.py

Description

• Main represents the launch point for pyLabManager. Nothing in main is ment to be hardcoded. Main initalizes the database, logging module, hardware manager, all insturment managers, and the HTTP server. It is also responsible for feeding certain objects down the hireacry. For instance, while the database object is created in main, it is handed down to the hardware manager, and by extension any instumrment managers.

Items that are indended to be created in main

• Any needed databases
• The HTTP server object
• The master hardware manager
  • Note: Registering all the insturment managers is indenteded to happen in main
• Individual Instument Managers
• Logging module init and configuration

Planned Functionality

• Move some of the configuration into an argument parser
• Loading insturment data / database configruations from a config file

Database

Description

• pyLabManager certainly didn't invent the concept of a non-volitile database, however it is an essential component of the software. The current database implementation serves multiple functions. It acts as a debugging device, records keeper, and transfering data between modules. The database library used is pickleDB, which is a lightweight JSON based library. Documentation for pickledb can be found here

• At a high level, there are three key'd lists in the database that are nessissary for the function of one insturment. In the case of the OSMO2020, there are osmoUnpairedSampleID, osmoUnpairedTimestamp, and OsmoUnsentLinkedData. These three lists hold keys that represent the states of various database entrys.

httpServer.py

Description

• The HTTP server represents the module that has contact with the outside world. The httpServer file contains a handler and a threaded python 2.7 BaseHTTPServer object. The server is designed such that the handler is to be expanded for each insturment. The OSMO2020 handler is described below.

OSMO2020 HTTP Command Structure

• The OSMO2020 HTTP Command has to account for 3 different states:
  • There is linked, unsent data
  • There is unlinked, unsent, ready data
  • There is no data ready to be sent
• The exact protocol executed for each statement can be found by looking at the code, however the HTTP protocol aheances are important. The OSMO command sends two flags: One 'Content-Type' of 'text' and one 'Status' which depends on which of the cases were executed. Additionally, the client is returned a formatted string with the sample ID results, and the well number with corresponding measurement.

Setup

• pyLabManager is almost entirely based on python-standard libraries, the only outside dependencies are pickledb and serial, not being packaged with a python2 standard distribution. These packages can be installed by using the pip utility, with the command pip install -r requirements.txt.

OSMO 2020 Serial Command Structure

The theory was, if enough log files were collected and analyzed carefully enough, you could get a good idea of what the command structure was, even without a users manuel. Thus, a majoiry of the commands and their respective byte patterns have been found. In the following documentation, the quotation marks denote the start and end of a message. They are not included in the sent message.

Recall Results

• Header : 19 Bytes
  • “1. Recall Results\r\n”
• Table Header : 116 Bytes
  • “ # Result ID Date/Time \r\n ==========================================================\r\n”
  • Need to come back to this to double check newline characters + spaces
  • 116 Bytes is an estimate from stitching together tests
• Results : 65 Bytes
  • "<space*2>199: 287 mOsm/kg<space*22>09/21/2019 09:36:14 AM\r\n"
  • For the record, we know for a fact the results are appended every 65 bytes, we don’t know for sure how often the heading is
  • TODO: Recount frame, seems to be off by a few bytes

Result Reporting (Doing a real test)

• Header : 111 Bytes
  • Operator ID: ___________________ SN: 05030326A 09/21/2019 10:32:33 AM ================================\r\n”
  • Note: This section is sent as 4 seperate messages, each terminated by a \r\n character.
• Result : 15 Bytes
  • " 6: 303 ID: \r\n”
• Footer : 60 Bytes
  • "================================\r\nTray Complete<space*11>\r\n""
  • Need to double check - Spaces at the end were manually counted from hex

Statistics

• Header : 15 Bytes
  • “2. Statistics\r\n”
• Data Range : 26 Bytes
  • “Start: 171 Stop: 200<space*3>\r\n”
  • Spaces hand counted
• Average : 25 Bytes
  • “Average = 304.9 mOsm/kg\r\n”
• Standard Deviation : 24 Bytes
  • “Std Dev = 22.5 mOsm/kg\r\n”
• Coefficient of variation : 12 Bytes
  • “CV = 7.39%\r\n”
  • Note: Stitched toegether from two separate log messages

Event Record

• Header : 18 Bytes
  • "3. Event Record\r\n”
• Note: This message will probabbly never be sent over, but it seems to be a large spew of recorded events

Barcode Test

• Header : 26 Bytes
  • “6. Barcode Test<space*9>\r\n”
• Note: This message is unfinished. It is one of the few messages where the logs were cut off

Assistance

• Header : 37 Bytes
  • “4. Assistance\r\nAdvanced Instruments\r\n”
• Road : 20 Bytes
  • “Two Technology Way\r\n”
• City and State : 20 Bytes
  • “Norwood, MA 02062\r\n”
• Telephone : 31 Bytes
  • “Telephone:\r\nUS: (781)320-9000\r\n”
• Fax : 33 Bytes
  • “Service Fax:\r\nUS: (781)320-0811\r\n”
• Supplies Fax : 34 Bytes
  • “Supplies Fax:\r\nUS: (781)320-3669\r\n”
• Internet : 32
  • “Internet:\r\nwww.aicompanies.com\r\n”
• Model / Firmware : 45 Bytes
  • “<space*7>Model 2020\r\nFirmware Version 2.2\r\n”
• Serial Number : 41 Bytes
  • “SN: 05030326A\r\nBlock: 5 Sample: 7\r\n”
  • The block and sample feilds here are unknown, espeically because this command is not used with any measurement command

Minor Commands

The following are commands are unlikely to be encountered in production enviroment. They result in little/no additional information being sent over serial besides the header.

A/D Tests

• Header : 14 Bytes
  • “1. A/D Tests\r\n”

Probe Bin Test

• Header : 19 Bytes
  • “2. Probe Bin Test\r\n”

Solenoid Test

• Header : 18 Bytes
  • “3. Solenoid Test\r\n”

Display/Print Test

• Header : 24 Bytes
  • “4. Display/Print Test\r\n”
• Test : 50 Bytes
  • “!?<>#$%&*()/0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ\r\n”

Key/beeper Test

• Header : 26 Bytes
  • “5. Key/Beeper Test<space*6>\r\n”

Barcode Test

• Header : 26 Bytes
  • “6. Barcode Test<space*9>\r\n”

Motor Test

• Header : 16 Bytes
  • “7. Motor Tests\r\n”

Select LIMS Out

• Header : 26 Bytes
  • “9. Select LIMS Out<space*6>\r\n”

Exit Configuration (?)

• Header : 14 Bytes
  • “Saving Setup\r\n”