=============== Beginners Guide =============== This is a detailed beginners guide to *eems*. 1. Preparation ============== Before you can read DS18B20 sensors with *eems* several preparations need to be done. 1.1 Hardware ------------ This section is under maintenance, meanwhile please use common references provided by the world wide web. 1.2 Software ------------ Following chapter provides information regarding necessary software preparations. 1.2.1 Installation ~~~~~~~~~~~~~~~~~~ Before you can use *eems*, it needs to be installed. This can be done via *pip* or *git*. Install via pip:: pip install eems Install via git:: git clone https://github.com/enricoba/eems.git cd eems/ python setup.py install 1.2.2 Check configurations ~~~~~~~~~~~~~~~~~~~~~~~~~~ Before you can star monitoring, system configurations need to be made. Before changing anything, a check function can be called to verify if any configurations are already set. Therefore, you can type following command into your terminal:: eems check Or run the check inside a python script:: import eems # generate check-object to identify ds18b20 requirements c = eems.Check() # check if modules w1-therm and w1-gpio are set c.w1_modules() # check if dtoverlay=w1-gpio is set in config.txt c.w1_config() 1.2.3 Prepare configurations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the configuration check told you that something is missing (either *modules* or *config.txt*), the necessary preparations can be done by typing following command into your terminal:: sudo eems prepare Or by calling the function inside a python script:: import eems # generate check-object to identify ds18b20 requirements c = eems.Check() # prepare configurations c.prepare() Be aware that you need to call the command or the python script with sudo rights! 2. Usage ======== The two main functions of *eems* are *read* and *monitor*. 2.1 Read -------- The command *read* reads all connected DS18B20 sensors once. The outputs are written into the console. This command mainly serves for testing issues. Command line:: eems read Python script (Object Temp also can accept parameters described in chapter 2.2.x) to activate console output, use *console=True*:: import eems # generate temp-object to read sensors t = eems.Temp(console=True) # Read all connected DS18B20 sensors once. t.read() 2.2 Monitor ----------- The command *monitor* reads all connected DS18B20 sensors in a defined interval over a certain duration. Additionally, optional parameters can be passed using command line. Running *monitor* via the command line with an interval of 2 seconds and a maximum duration of 10 seconds:: eems monitor -i 2 -d 10 The same result can be achieved inside a python script:: import eems # generate temp-object to read sensors t = eems.Temp(console=True) # Start reading DS18B20 sensors with an interval of 2s and a maximum # duration of 10s t.monitor(interval=2, duration=10) Default interval is 60 seconds and default duration is infinity. *monitor* can be interrupted by pressing Ctrl-C at any time. If a duration is defined, *monitor* stops after the duration has passed. 2.2.1 Csv ~~~~~~~~~ The first option is *csv*. By activating, a csv file is created and all sensor measurements are written into the file. Command line example:: eems monitor -i 2 -d 10 --csv Python script example:: import eems # generate temp-object to read sensors and write temperatures into csv file t = eems.Temp(csv=True) # Start reading DS18B20 sensors with an interval of 2s and a maximum # duration of 10s t.monitor(interval=2, duration=10) 2.2.2 Log ~~~~~~~~~ The second option is *log*. By activating, a log file is created and all outputs are written into it. Command line example:: eems monitor -i 2 -d 10 --log Python script example:: import eems # generate temp-object to read sensors and writing outputs to log file t = eems.Temp(log=True) # Start reading DS18B20 sensors with an interval of 2s and a maximum # duration of 10s t.monitor(interval=2, duration=10) 2.2.3 Console ~~~~~~~~~~~~~ The third and last option is *console*. By activating, all outputs are written into the console/terminal similar to print. Command line example:: eems monitor -i 2 -d 10 --console Python script example:: import eems # generate temp-object to read sensors and write to console t = eems.Temp(console=True) # Start reading DS18B20 sensors with an interval of 2s and a maximum # duration of 10s t.monitor(interval=2, duration=10) 2.3 Examples ------------ Examples for daily use. 2.3.1 Background process ~~~~~~~~~~~~~~~~~~~~~~~~ One easy way to establish an easy monitoring system is to call the console command as a background process. This is achieved by adding *&* at the end of the command. That scenario also perfectly links with using csv file exports and the log file. Command line example:: eems monitor -i 2 -d 60 --csv --log & Either *monitor* ends after the duration has passed or the process is killed manually. This can be achieved by using typing following command:: kill Thereby, needs to be replaced with the process pid. You can find the pid in the console after calling *monitor* or inside the log file.