<commit_before>=============================
How to use the UT330 software
=============================

Introduction
============

I work in an office and I thought the temperature was changing more than was comfortable through the day. Sometimes I would be cold and sometimes hot. I wanted a cheap temperature logger to monitor the temperature so I could display the temperature history as a chart. 

I looked online on `AliExpress <http://www.aliexpress.com/>`_ and found the UT330B, a USB battery powered temperature and humidity logger. It was cheap ($35) and did what I wanted. The only problem was, it only had Windows software to control it and I use a Mac. It worked via a USB port, so I thought I could figure out the commands sent over the USB port and build something myself. With great help from `<NAME> <https://github.com/pjsg>`_, I did it. This project is a result of that effort.

With this software, you can control the UT330B, or other UT330 devices, from any platform that runs Python and has a USB port. In the appendices, I list some of the UT330 devices and tell you where you can buy them.

What’s in the software package?
===============================

All of the software was built on Python 2.7 using the Anaconda distribution.

UT330
-----

This is the code that provides an interface to the UT330B. It’s fully commented and PEP8 compliant. 

Test
----

This is a simple script that demonstrates all of the UT330B methods. Note that the script will delete all data on the device and do a factory reset. Please be careful using it!

UI
--

This is a small system I’ve written using Bokeh to provide a UI to the device.

Documentation
-------------

This text.

License
-------

I’m using the MIT License.

Using the UT330 object – a short tutorial
=========================================

Dependencies
------------

The UT330 object depends on the following libraries:

* datetime
* pyserial (version 3.01)
* time

If you don’t already have them, you can install them with the pip install command.

You may also have to install a device driver. If this is the case, please let me know and I’ll add details.

Connect and read the device name
--------------------------------

For any of this to work, you must connect the UT330 to a USB port on your system.

The software has been designed to work with the Python with command, just like a file object. Here’s how. ::

    from ut330 import UT330

    with UT330() as ut330:                
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"                 
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ Reading device name ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"        
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"              
        print "Device name = {0}".format(ut330.read_device_name())

Here, the UT330 is opened and a variable (ut330) initialized. The function read_device_name is called on the ut330 object and the name is printed. You should see an output something like this.::

    ut330b

Read the offsets
----------------

The UT330B allows you to set temperature and humidity offsets, allowing you to calibrate it. Here’s how you can read the offsets. ::

    from ut330 import UT330

    with UT330() as ut330:      
    print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"    
    print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ Reading offsets ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
    print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
    
    offsets = ut330.read_offsets()
    print offsets

The offsets variable is a very simple Python dict: ::

    offsets= {	'temperature offset': 0,                        
                'humidity offset': 0,                        
                'pressure offset': 0}

The UT330B does not have a pressure sensor, so the pressure offset is irrelevant.

Reading the data
----------------

The temperature, humidity, and pressure data can be read from the device using the read_data() method. Here’s an example that shows reading the data and printing the result. ::
    
    # Read data   
    with UT330() as ut330:           
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ Reading data ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"   
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
        DATA = ut330.read_data()              

    if DATA != []:                  

        print  'Timestamp, Temperature (C), Relative humidity (%), Pressure (Pa)\n'   
    
    for data_line in DATA:                          
        line = "{0}, {1}, {2}, {3}\n". format(data_line['timestamp'],
                                              data_line['temperature'],
                                              data_line['humidity'],
                                              data_line['pressure'])                                                   
        print line[:-1]

Change the configuration
------------------------

As well as read data from the UT330B, you can also change its settings. Here, I’ll just show one example, changing the configuration information.

To do this, we have to create a dict which must be defined like this: ::

    CONFIG = {'device name': 'UT330B',                       
              'sampling interval': 300,                       
              'overwrite records': False,                      
              'delay timing': 120,                       
              'delay start': True,                       
              'high temperature alarm': 40,                       
              'low temperature alarm': -10,                       
              'high humidity alarm': 95,                       
              'low humidity alarm': 10}
<commit_msg>Update documentation.rst<commit_after>=============================
How to use the UT330 software
=============================

Introduction
============

I work in an office and I thought the temperature was changing more than was comfortable through the day. Sometimes I would be cold and sometimes hot. I wanted a cheap temperature logger to monitor the temperature so I could display the temperature history as a chart. 

I looked online on `AliExpress <http://www.aliexpress.com/>`_ and found the UT330B, a USB battery powered temperature and humidity logger. It was cheap ($35) and did what I wanted. The only problem was, it only had Windows software to control it and I use a Mac. It worked via a USB port, so I thought I could figure out the commands sent over the USB port and build something myself. With great help from `<NAME> <https://github.com/pjsg>`_, I did it. This project is a result of that effort.

With this software, you can control the UT330B, or other UT330 devices, from any platform that runs Python and has a USB port. In the appendices, I list some of the UT330 devices and tell you where you can buy them.

What’s in the software package?
===============================

All of the software was built on Python 2.7 using the Anaconda distribution.

UT330
-----

This is the code that provides an interface to the UT330B. It’s fully commented and PEP8 compliant. 

Test
----

This is a simple script that demonstrates all of the UT330B methods. Note that the script will delete all data on the device and do a factory reset. Please be careful using it!

UI
--

This is a small system I’ve written using Bokeh to provide a UI to the device.

Documentation
-------------

This text.

License
-------

I’m using the MIT License.

Using the UT330 object – a short tutorial
=========================================

Dependencies
------------

The UT330 object depends on the following libraries:

* datetime
* pyserial (version 3.01)
* time

If you don’t already have them, you can install them with the pip install command.

You may also have to install a device driver. If this is the case, please let me know and I’ll add details.

Connect and read the device name
--------------------------------

For any of this to work, you must connect the UT330 to a USB port on your system.

The software has been designed to work with the Python with command, just like a file object. Here’s how. ::

    from ut330 import UT330

    with UT330() as ut330:                
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"                 
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ Reading device name ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"        
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"              
        print "Device name = {0}".format(ut330.read_device_name())

Here, the UT330 is opened and a variable (ut330) initialized. The function read_device_name is called on the ut330 object and the name is printed. You should see an output something like this.::

    ut330b

Read the offsets
----------------

The UT330B allows you to set temperature and humidity offsets, allowing you to calibrate it. Here’s how you can read the offsets. ::

    from ut330 import UT330

    with UT330() as ut330:      
    print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"    
    print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ Reading offsets ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
    print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
    
    offsets = ut330.read_offsets()
    print offsets

The offsets variable is a very simple Python dict: ::

    offsets= {	'temperature offset': 0,                        
                'humidity offset': 0,                        
                'pressure offset': 0}

The UT330B does not have a pressure sensor, so the pressure offset is irrelevant.

Reading the data
----------------

The temperature, humidity, and pressure data can be read from the device using the read_data() method. Here’s an example that shows reading the data and printing the result. ::
    
    # Read data   
    with UT330() as ut330:           
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ Reading data ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"   
        print "▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉"     
        DATA = ut330.read_data()              

    if DATA != []:                  

        print  'Timestamp, Temperature (C), Relative humidity (%), Pressure (Pa)\n'   
    
        for data_line in DATA:                          
            line = "{0}, {1}, {2}, {3}\n". format(data_line['timestamp'],
                                                  data_line['temperature'],
                                                  data_line['humidity'],
                                                  data_line['pressure'])                                                   
            print line[:-1]

Change the configuration
------------------------

As well as read data from the UT330B, you can also change its settings. Here, I’ll just show one example, changing the configuration information.

To do this, we have to create a dict which must be defined like this: ::

    CONFIG = {'device name': 'UT330B',                       
              'sampling interval': 300,                       
              'overwrite records': False,                      
              'delay timing': 120,                       
              'delay start': True,                       
              'high temperature alarm': 40,                       
              'low temperature alarm': -10,                       
              'high humidity alarm': 95,                       
              'low humidity alarm': 10}

{'fraction_non_alphanumeric': 0.16985750502666316, 'fraction_numerical': 0.022204738176414024, 'mean_word_length': 2.121418826739427, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1531755', 'n_tokens_mistral': 5243, 'n_tokens_neox': 4095, 'n_words': 1321}