README : jHomeNet server Released : July 16, 2007 Version : 0.4 build 1345 Written by : Dave Irwin (jhomenet at gmail dot com) _________________________________________________________________________________ OVERVIEW jHomeNet server is an application developed to help manage and control a collection of hardware sensors and devices. The hardware includes Dallas Semiconductor 1-Wire and X-10 sensors and devices. The software can be used as a home-automation system. Currently, the jHomeNet suite contains two basic core components: 1) a hardware management system, and 2) a sensor responsive system. The hardware management system is responsive for managing the hardware on the 1-Wire and X10 networks. This includes registering the hardware, managing specific hardware details and communication to the hardware, as well as presenting a graphical view of the hardware to the user. The hardware manage system has been included since version 0.1 of the jHomeNet server. The sensor responsive system can be used to execute certain responses based on a set of conditions. For example, a condition might be if the temperature of a certain temperate sensor is greater than a 90F, execute an email response that would automatically send an email with pertitent information. The sensor responsive system was initially released as part of jHomeNet server version 0.4. This release is considered an beta release of the software and as such is still under a considerable amount of development. Expect major changes in the API between this and future releases of the jHomenet server. Not all features are implemented in this release. This release also does not contain all the necessary documentation. This release was published in order to provide a preview to users of features in development. The distribution (once built) includes the following folder and files: o conf contains configuration files o docs contains documentation including the API o images contains any necessary images o lib contains all the necessary library files o logs contains any log files produced by the jHomenet server o persistence contains any file based persistence files o plugins contains any jHomenet server plugins o resources contains any other resource files o src source tree In addition, the current distribution also includes an Apache Ant build file (build.xml) for building the application from the source and a Windows batch files for running the application. NOTE: This release of the jHomeNet server does not contain a binary jHomeNet server Jar file. The server must be built from the included source files. _________________________________________________________________________________ GENERAL INFORMATION Refer to the jHomenet Sourceforge project website (http://jhomenet.sourceforge.net/) for general information about the jHomenet suite of applications. To post a comment or a request for help, visit the following website: https://sourceforge.net/forum/?group_id=140953. Alternatively, send an email to the project email address at jhomenet@gmail.com. To report a bug, use the bug submit form found on the Sourceforge website at the following address: https://sourceforge.net/tracker/?func=add&group_id=140953&atid=747884. _________________________________________________________________________________ RUNTIME ENVIRONMENT Several sections of the software has been developed using Sun's JDK 1.6 software development kit features. As such, it's required that Sun's latest 1.6 compatible JRE be installed to run the applications, and Sun's lastest 1.6 compatible SDK be installed to for development. Development of the current version of the jHomenet server has used JDK 1.6. In order to make use of the included build files, a copy of Apache Ant should be installed and properly configured. A copy of Ant can be freely downloaded from the following site: http://ant.apache.org/. Eclipse 3.1 was used for development along with Ant version 1.6.1. _________________________________________________________________________________ SOURCE COMPILING The project comes with an Apache Ant build.xml file for use in compiling the source. To build the Java sources for the jHomeNet server only, at the command line type: jhomenet-server> ant This builds the sources and places the compiled class files in the build\classes folder. The process also copies the necessary configuration, library, and image files to the correct folder within the build\classes root directory. The current distribution does not include pre-compiled binary class files. Note: at this point, if no changes to the jHomeNet commons or UI packages were made, you may move onto configuring and setting up the jHomeNet server. The jHomeNet server is dependent on both a number of third party libraries as well as the jHomeNet commons and UI libraries. If changes are made in the jhomenet-commons or jhomenet-ui libraries, they will need to be built and the binary library Jar files placed in the jhomenet-server lib folder before building the jhomenet-server. The table below summarizes the jhomenet package dependencies: Package jHomenet Dependency ------- ------------------- jhomenet-commons None jhomenet-ui jhomenet-commons jhomenet-server jhomenet-commons, jhomenet-ui Build the jhomenet-commons package first. Copy of jhomenet-commons Jar file to the jhomenet-commons package. Then build the jhomenet-ui package. Then copy both the jhomenet-commons and jhomenet-ui Jar files to the jhomenet-server package. Build the jhomenet-server package. If no changes are made to the jhomenet-commons or jhomenet-ui packages then they do not need to be rebuilt. Refer to package specific readme files for specific build directions. Fortunately, an Ant task is included with the jHomeNet server package that does all this package building and copying automatically. This Ant task will build the jHomeNet commons library and the jhomenet-ui library and copy them to the jhomenet-server package as necessary. However, you MUST configure the jhomenet-server's Ant configuration before running this Ant task. To do this, open the jhomenet-server's default.properties file located in the jhomenet-server root directory. Under the "jHomeNet suite full-build properties" section toward the bottom of the file, edit the necessary entries to to point to the jhomenet-common and jhomenet-ui project folders. In particular, you will want to edit the "commons-package.dir" line and the "ui-package.dir" line to point to the particular project folders. Once the jhomenet-server's Ant configuration has been properly editted, build the full jHomeNet suite by typing the following at the command line type: jhomenet-server> ant build-suite Alternatively, if a clean build of the entire suite is desired, you may do this by running the following command at the command line: jhomenet-server> ant build-clean-suite _________________________________________________________________________________ CONFIGURING & SETTING UP THE SERVER The jHomeNet server runs based on a configuration file called jhomenet.cfg.xml located in the \conf\ folder. This configuration file specifies other configuration files that are to be used to load resources. In particular, jhomenet.cfg.xml file also specifies the hardware configuration file that defines the available hardware types and hardware drivers used. By default, the jhomenet.cfg.xml file defines a hardware_test.cfg.xml file for the hardware configuration. This test hardware configuration file contains definitions for dummy or mock hardware definitions. Doing this enables a user to get the server up and running without requiring any actual 1-Wire or X10 hardware sensors or devices installed and without actually installing any of the 1-Wire and X10 drivers. This allows for development of the jHomeNet server without actually having a 1-Wire or X10 network installed. Note: when using dummy or mock hardware, any data created will be based on a random number generator and does not correspond to any actual real-world hardware data. To use the jHomeNet server with an actual 1-Wire or X10 network, edit the jhomenet.cfg.xml configuration file and change the hardware configuration file to hardware.cfg.xml. You may want to further refine the jhomenet.cfg.xml hardware configuration file to match your exact network design and needs. To communicate with actual 1-Wire and X-10 hardware, the necessary 1-Wire and X-10 drivers also need to be installed properly prior to running the server. The 1-Wire drivers allow access to the 1-Wire communication network using Java and may be downloaded from http://www.maxim-ic.com/products/ibutton/software/tmex/index.cfm (for Windows only). The driver for communicating using the X-10 communication network is distributed as part of the jhomenet-server package. After installing the communication drivers, no other configuration should be required. The jHomeNet server requires a SQL database to store hardware data, persist jHomeNet entity objects, and store other configuration information. The database server must be installed and configured before running the jHomeNet server. For development, MySQL server 5.0.37-community-nt on a Windows machine was used. To configure the SQL server, install the server and create a user and password for accessing the server. Once the SQL server has been installed and setup, a jHomeNet database must be created and configured with the necessary tables and foreign before running the server. Fortunately, an Ant task is included that will automate the process of creating the jHomeNet database, tables, and foreign keys. To run this Ant task, at the command line, type: jhomenet-server> ant init-db Note: as of the most recent release, running this target will delete all the contents of the database including any previously registered hardware entities and sensor responsive entities. Note: you will be required to edit the hibernate.cfg.xml configuration file in the conf\ folder to include the pertinent database URL, username, and password information in order for the init-db task and the jhomenet-server to properly work. You MUST edit the hibernate.cfg.xml file prior to proceeding. _________________________________________________________________________________ RUNNING THE SERVER At this point, the system should be properly configured and ready for execution. You can start the server by running one of the included Windows batch files. At this time, a Linux script is not included. In particular, to start the server at the command line type: jhomenet-server> server_dev During the server startup, the server will ask for user authentication. The default username and password is admin/admin. Note: the current release allows a user to create a new user and password once authenticated. At this current time, the user authentication provides full access to the system. Future releases will include a user authorization component in addition the user authentication. If everything has been configured correctly, the user should be presented with the main jHomeNet interface containing a tree on left side and a desktop on the right.