extensions/net.sf.basedb.labenv/trunk/README

Code
Comments
Other
Rev Date Author Line
2542 03 Jul 14 olle 1 == Component name ==
2542 03 Jul 14 olle 2
3874 25 Apr 16 nicklas 3 Name: LabEnv
2542 03 Jul 14 olle 4 Type: BASE extension
2542 03 Jul 14 olle 5 Full name: Lab Environment Extension
2542 03 Jul 14 olle 6
2317 04 Apr 14 olle 7 == Requirements ==
2317 04 Apr 14 olle 8
5513 19 Jun 19 nicklas 9  1. BASE 3.15 or later.
5513 19 Jun 19 nicklas 10  2. Java 11 or later.
5513 19 Jun 19 nicklas 11  
2317 04 Apr 14 olle 12 == Introduction ==
2317 04 Apr 14 olle 13
2317 04 Apr 14 olle 14 This package is an extension package to BASE that allows storage of
2317 04 Apr 14 olle 15 regular measurements of lab environment data through ThermoWorks
2317 04 Apr 14 olle 16 Thermo Recoder TR-702W sensors placed in the labs, and inspection
2317 04 Apr 14 olle 17 of the stored values.
2317 04 Apr 14 olle 18
2317 04 Apr 14 olle 19  * The homepage for this extension: 
2317 04 Apr 14 olle 20    http://baseplugins.thep.lu.se/wiki/net.sf.basedb.labenv
2317 04 Apr 14 olle 21
2317 04 Apr 14 olle 22 == Installation ==
2317 04 Apr 14 olle 23
3022 09 Dec 14 nicklas 24 When updating see notes below!
3022 09 Dec 14 nicklas 25
2317 04 Apr 14 olle 26  1. Download the `labenv-*.tar.gz` file.
2317 04 Apr 14 olle 27  2. Unpack the downloaded file to a directory of your choice.
3022 09 Dec 14 nicklas 28  3. Copy the `labenv-config.xml` file to `WEB-INF/classes` directory.
3022 09 Dec 14 nicklas 29  4. The default `labenv-config.xml` file does not contain any useful
2542 03 Jul 14 olle 30     configuration values, but has to be edited with information
2542 03 Jul 14 olle 31     on the lab sensors.
2542 03 Jul 14 olle 32     a. Configuration of database for lab environment data and settings
3022 09 Dec 14 nicklas 33     common for all lab sensors. If no values are given for 
2542 03 Jul 14 olle 34     "timeoutinseconds", "storageintervalinseconds", and
3022 09 Dec 14 nicklas 35     "numberofmeasurementsperstoredvalue", default values 
2542 03 Jul 14 olle 36     5, 300, and 5, will be used, respectively. This corresponds to
2542 03 Jul 14 olle 37     measurements each minute and storage of the average values every
2542 03 Jul 14 olle 38     5th minute. If alarm notification via e-mail is desired, information
2542 03 Jul 14 olle 39     about what e-mail server to use must be entered for "smtphost".
2542 03 Jul 14 olle 40     Attribute "fromaddress" is the e-mail address shown in the
2542 03 Jul 14 olle 41     "From"-field for the mail; normally this is of the type
2542 03 Jul 14 olle 42     "noreply@*" here, e.g. "noreply@thep.lu.se". Attribute "fromname"
2542 03 Jul 14 olle 43     is the name part of the "From"-field for the mail, e.g. something
2542 03 Jul 14 olle 44     generic like "Lab Environment BASE extension", or something more
2542 03 Jul 14 olle 45     specific for your BASE server or lab.
2542 03 Jul 14 olle 46     b. Measurement data will be stored in the database for the sensor
2542 03 Jul 14 olle 47     number defined in the configuration file. This lab sensor number
2542 03 Jul 14 olle 48     is therefore not just a trivial index number for internal use in
2542 03 Jul 14 olle 49     the XML configuration file. When sensors are added for new
2542 03 Jul 14 olle 50     locations, they should normally be configured with a new unique
2542 03 Jul 14 olle 51     number. If no "startdate" is given for a sensor, it will be ignored.
2542 03 Jul 14 olle 52     c. Alarm configuration for a lab sensor is optional. One or more
2542 03 Jul 14 olle 53     alarm configurations can be entered for each sensor. Each alarm
2542 03 Jul 14 olle 54     configuration contains start and end time in "HHmm" format,
2542 03 Jul 14 olle 55     a weekday filter with one of the values "all", "mondaytofriday",
2542 03 Jul 14 olle 56     "saturdaytosunday", "workdays", or "nonworkdays" (last two entries
2542 03 Jul 14 olle 57     are currently adapted to the automatic climate control at labs
2542 03 Jul 14 olle 58     in Medicon Village, Lund University, Sweden), minimum and maximum
2542 03 Jul 14 olle 59     allowed values for temperature and humidity, and a user list
2542 03 Jul 14 olle 60     of alarm administrators. For each alarm administrator is entered
2542 03 Jul 14 olle 61     the BASE log-in name ("id"), and an optional e-mail address for
2542 03 Jul 14 olle 62     alarm notification.
2345 09 Apr 14 olle 63  6. Copy the 'labenv.jar' file to your BASE plug-ins directory. 
2542 03 Jul 14 olle 64     Look in your 'base.config' file if you don't know where this is.
2345 09 Apr 14 olle 65  7. Go to 'Administrate->Plug-ins & Extensions->Overview' page.
2345 09 Apr 14 olle 66  8. Run the installation wizard and select to install 'labenv.jar'.
2345 09 Apr 14 olle 67  9. The LabEnv Server should now be running, and collect data from the
2317 04 Apr 14 olle 68     configured sensors regularly, and store the average values in the
2317 04 Apr 14 olle 69     local database. The BASE `Extensions` menu should now have a new
2317 04 Apr 14 olle 70     cascade menu entry `Lab Environment`, with child menu items for
2317 04 Apr 14 olle 71     different functionality of the extension, such as retrieving
2317 04 Apr 14 olle 72     configuration data from the sensors, or inspecting the data stored
2317 04 Apr 14 olle 73     in the database.
2345 09 Apr 14 olle 74 10. If the BASE server running the LabEnv extension is placed at a
2317 04 Apr 14 olle 75     location different from that of the labs, where the sensors are
2317 04 Apr 14 olle 76     installed, firewalls must be configured to allow the BASE server
2317 04 Apr 14 olle 77     to access the internal web servers of the sensors, for lab
2317 04 Apr 14 olle 78     environment data to be collected (port 80 has to be opened).
2345 09 Apr 14 olle 79 11. Done.
2317 04 Apr 14 olle 80
3022 09 Dec 14 nicklas 81 == Update notes ==
3022 09 Dec 14 nicklas 82
3022 09 Dec 14 nicklas 83 Since LabEnv 1.3 SQLite is no longer used for storing measurements. Instead,
3022 09 Dec 14 nicklas 84 LabEnv uses the same database that BASE uses. Existing data is automatically
3366 04 Jun 15 nicklas 85 migrated to the BASE database in LabEnv 1.3, but this feature has been removed
3366 04 Jun 15 nicklas 86 in LabEnv 1.4.
3022 09 Dec 14 nicklas 87
3366 04 Jun 15 nicklas 88 NOTE! If you are running LabEnv 1.2 or earlier and want to upgrade to LabEnv 1.4
3366 04 Jun 15 nicklas 89 or later, you should first update to LabEnv 1.3 if you want to keep the old data.
3366 04 Jun 15 nicklas 90
3366 04 Jun 15 nicklas 91 To avoid mistakes by migrating the same SQLite database more than once a number 
3366 04 Jun 15 nicklas 92 of precautions have been taken:
3366 04 Jun 15 nicklas 93
3022 09 Dec 14 nicklas 94  * Measurements that fall within 5 minutes of an existing measurement are
3022 09 Dec 14 nicklas 95    ignored.
3022 09 Dec 14 nicklas 96  * If the migration is successful the SQLite database file will be removed. 
3022 09 Dec 14 nicklas 97
3022 09 Dec 14 nicklas 98
2317 04 Apr 14 olle 99 == Known issues ==
2317 04 Apr 14 olle 100
2317 04 Apr 14 olle 101  * No known issues. 
2542 03 Jul 14 olle 102
2317 04 Apr 14 olle 103 == Tips and tricks ==
2317 04 Apr 14 olle 104
2317 04 Apr 14 olle 105  * It is recommended to configure the extension to make a number
2317 04 Apr 14 olle 106    of measurements per stored value, as this will reduce the
2317 04 Apr 14 olle 107    instrument noise in the stored data (the average value will be
2317 04 Apr 14 olle 108    stored), and reduce the size of the database.
2317 04 Apr 14 olle 109  * If a lab sensor is out of work for a longer time period (whether
2317 04 Apr 14 olle 110    due to problem with the sensor or the network connection),
2317 04 Apr 14 olle 111    you can configure the LabEnv extension to skip this sensor,
2317 04 Apr 14 olle 112    when acquiring data. This is done by setting the start date for
2317 04 Apr 14 olle 113    the sensor in question to a blank value in the configuration file
2317 04 Apr 14 olle 114    `labenv-config.xml`, and restarting the extension.
2317 04 Apr 14 olle 115  * If a malfunctioning sensor for an important location needs to be
2317 04 Apr 14 olle 116    temporarily exchanged for a working sensor internally configured
2317 04 Apr 14 olle 117    for a another, less important, location, and there is no time to
2317 04 Apr 14 olle 118    re-configure the latter sensor internally, the lab environment
2317 04 Apr 14 olle 119    configuration file can be modified so the measurements from the
2317 04 Apr 14 olle 120    temporary sensor are stored for the sensor number of the
2489 05 Jun 14 olle 121    malfunctioning one.
2317 04 Apr 14 olle 122
2317 04 Apr 14 olle 123 == Compiling ==
2317 04 Apr 14 olle 124
2317 04 Apr 14 olle 125 To compile this package you also need:
2317 04 Apr 14 olle 126  
5513 19 Jun 19 nicklas 127  1. Ant 1.10
5513 19 Jun 19 nicklas 128  2. Java 11
2317 04 Apr 14 olle 129
2317 04 Apr 14 olle 130 Follow these instructions:
2317 04 Apr 14 olle 131
2317 04 Apr 14 olle 132  1. Download the source code from the subversion repository. See
2317 04 Apr 14 olle 133     http://baseplugins.thep.lu.se/wiki/net.sf.basedb.labenv for instructions.
2317 04 Apr 14 olle 134  
2317 04 Apr 14 olle 135  2. Type `ant download-lib` to automatically download the BASE core JAR file that
2317 04 Apr 14 olle 136     are needed for compilation. You can also do this manually by copying the 
2489 05 Jun 14 olle 137     base-core-3.*.jar and base-webclient-3.*.jar files from the BASE installation
2489 05 Jun 14 olle 138     directory (`<basedir>/www/WEB-INF/lib/`) to the `./lib/compile` directory.
2317 04 Apr 14 olle 139
2317 04 Apr 14 olle 140  3. Type `ant` to compile the code and generate the `labenv.jar` file
2317 04 Apr 14 olle 141     in the project directory.
2317 04 Apr 14 olle 142
2317 04 Apr 14 olle 143  4. Use `ant package` to create a downloadable tar.gz package.
2317 04 Apr 14 olle 144  
2317 04 Apr 14 olle 145 Tip: If you need different values for any of the properties defined in
2317 04 Apr 14 olle 146 the 'build.xml' file, create a file named 'build.properties' and set
2317 04 Apr 14 olle 147 the values there.
2542 03 Jul 14 olle 148
2542 03 Jul 14 olle 149 == Alarm functionality ==
2542 03 Jul 14 olle 150
2542 03 Jul 14 olle 151 * After an alarm has been reported, new alarm reports for that
2542 03 Jul 14 olle 152 configuration are normally blocked, until an alarm administrator
2542 03 Jul 14 olle 153 resets the alarm. An exception is alarm for lost contact with the
2542 03 Jul 14 olle 154 sensor, that blocks alarms of the same type, but not alarms for
2542 03 Jul 14 olle 155 temperature or humidity values outside allowed values, if contact with
2542 03 Jul 14 olle 156 the sensor should be reestablished.
2542 03 Jul 14 olle 157 * All alarms are reset if the Lab Environment service is restarted.
2542 03 Jul 14 olle 158 * All users can inspect alarm status via menu Extensions ->
2542 03 Jul 14 olle 159 Lab Environment -> Lab environment alarms, but only an alarm
2542 03 Jul 14 olle 160 administrator for an alarn can reset it. It is reset by setting option
2542 03 Jul 14 olle 161 "Alarm blocked" to "No" and clicking button "Set alarm blocker".

Generated on Tue Nov 21 03:25:32 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)