GNUrc

GNUrc is the GNU Remote Control software. That's the software that aids in the maintenance of your thermostats. For other projects see projects.

Status

v1.1 released, v2.0 under development.

Motivation

To seek operational efficiencies in air-conditioners thereby saving electricity and improving comfort.

Administration

Contributors

Members who have contributed to this project. Newest on top.

• John Elliot V

All contributors have agreed to the terms of the Contributor License Agreement. This excludes any upstream contributors who tend to have different administrative frameworks.

Upstream (GNU) contributors: GNU Remote Control Contributors

Copyright

Copyright 2015, Contributors.

License

Licensed under the AGPL.

Resources

Downloads

See the home page for downloads.

Source code

See the home page for source code.

Links

• www.gnurc.com, the GNUrc developer portal

Jargon

Following are definitions for abbreviations and acronyms that we use:

svn

Subversion version control software

i18n

intl

Internationalization/translation

SQL

Structured Query Language

API

Application Programming Interface

MVC

Model/View/Controller

ORM

Object/Relational Mapping

BOM

Business Object Model

HTML

HyperText Markup Language

HTTP

Hypertext Transfer Protocol

XSRF

Cross-Site Request Forgery

AJAX

Asynchronous JavaScript and XML

Functional specification

The functional specification describes what the project does.

Administration dashboard

The administration dashboard is an administrator's home page. From the administration dashboard an administrator can access:

1. User administration
2. Language administration
3. Group administration
4. Error reporting

Role-based security

We use role-based security to limit system functions to particular classes of users. There are three user roles and any given user can be in any combination of the roles:

1. Administrator
2. Translator
3. Standard

Administrators have access to administration functions. Non-administrators do not have access to administration functions. Translators have access to translation functions. Non-translators do not have access to translation functions. All users have access to the standard functions.

Technical specification

The technical specification describes how the project works.

Software layers

The GNUrc software is layered:

Layer	Directory	MVC role
modules	/src/1-lib	function libraries
objects	/src/2-obj	Model
Data Access Layer (DAL)	/src/3-dal	Model
Object/Relational Mapping (ORM)	/src/4-orm	Model
Business Object Model (BOM)	/src/5-bom	Model
views	/src/6-view	View
ajax	/src/7-ajax	Controller
controllers	/web	Controller

Each level depends on (up to) all of the previous levels. So controllers use views, BOM, ORM, DAL, objects, and modules. Views use BOM, ORM, DAL, objects, and modules. The BOM uses the ORM, DAL, objects, and modules. And so on. Generally controllers should call on the services of the BOM rather than calling on the services of the DAL directly, so the BOM encapsulates business logic and mediates it into the DAL. If higher layers can encapsulate functionality in lower layers that is a good thing to do.

Directory structure

The software has the following directory structure starting in the base:

/

The base directory is /path/to/your/gnurc.

• .svn-ignore -- files for Subversion (svn) to ignore

  e.g.: $ svn propset svn:ignore -RF .svn-ignore .

• config.example.php -- an example config file
• config.php -- the production config file

  e.g.: $ cp config.example.php config.php; vim config.php

/dat

The /dat directory is for data files.

• lang.dat -- the language subtag registry
• lang.ser -- the serialized PHP data-structure of the processed lang.dat file.

/etc

The /etc directory is for miscellaneous scripts.

• download-language-data.sh -- downloads the lang.dat file

/etc/dbscripts

The /etc/dbscripts directory is an svn:externals for the database scripts:

svn://svn.sv.gnu.org/remotecontrol/branches/development/dbscripts

• .svn-ignore -- files for Subversion (svn) to ignore
• .svn-ignore.sh -- a script to apply the svn-ignore settings.
• README.md -- the README file for the dbscripts.
• gnurc-db.sql -- a script to create a "gnurc" database.
• gnurc-schema.sql -- a script to apply the GNUrc schema to the 'current' database.
• gnurc-data.sql -- a script to insert default/global data.
• gnurc-test.sql -- a script to load test data.
• make-db.sh -- a script to create/upgrade a GNUrc database.

/src

The /src directory is for most of the source code.

• include.php -- the main include file for loading the GNUrc software components.
• test.php -- the main include file for use by PHPUnit unit tests.

/src/1-lib

The /src/1-lib directory contains function modules.

• 01-api.php -- an API for singletons and helper methods.
• 02-constants.php -- constants definitions.
• 20-array.php -- functions for working with arrays.
• 25-types.php -- functions for determining data types.
• 29-conversion.php -- functions for converting values.
• 30-formatting.php -- functions for formatting data.
• 35-validation.php -- functions for validating data.
• 37-defaults.php -- default settings.
• 40-late-constants.php -- late message and error definitions.
• 45-intl.php -- i18n helper functions/API.
• 55-calc.php -- functions for calculating.
• 60-html.php -- functions for working with HTML.
• 65-http.php -- functions for working with HTTP.
• 70-comparison.php -- comparison functions.
• 75-logic.php -- miscellaneous program logic.
• 80-datetime.php -- functions for working with dates and times.
• 98-handlers.php -- functions for error and exception handling.
• 99-screen.php -- global program logic.

/src/2-obj

The /src/2-obj directory contains PHP classes used by GNUrc that do not fit in another category.

• GrcDataPage.php -- represents and manipulates pagination settings.
• GrcDataSort.php -- represents and manipulates sorting settings.
• GrcError.php -- the API for declaring and raising software errors.
• GrcHtmlComposite.php -- an object to contain a list of HTML elements.
• GrcHtmlElement.php -- a class to model a HTML element. The global arrays in this file describe the various support for HTML by HTML4, XHTML and HTML5.
• GrcHtmlView4.php -- a class for rendering HTML 4.
• GrcHtmlView5.php -- a class for rendering HTML 5.
• GrcHtmlViewX.php -- a class for rendering XHTML.
• GrcIntl.php -- a class to support an internationalization (i18n) API.
• GrcListShuffler.php -- an object for shuffling a list, i.e. remove/first/previous/next/last.
• GrcMessage.php -- a class for declaring system messages (and aiding their translation).
• GrcPageLinks.php -- a class for modelling page links, e.g. first/last/next/previous/size=N/etc.
• GrcTableView.php -- a class for rendering tabular data as HTML.
• GrcUrl.php -- an API for modelling URLs.
• GrcValidation.php -- an API for data validation.

/src/3-dal

The /src/3-dal directory contains data access layer facilities.

• GrcDal.php -- the include file for the Data Access Layer; defaults to MySQL/PDO API.

/src/3-dal/mysql-pdo

The /src/3-dal/mysql-pdo directory contains data access layer facilities for the MySQL/PDO database connectivity.

/src/3-dal/*/feature

The /src/3-dal/*/feature directories contain DAL features.

/src/7-ajax

The /src/7-ajax directory contains AJAX controllers.

Managing errors

The error management subsystem is comprised of the /src/2-obj/GrcError.php class and the 'err' and 'Error' functions in /src/1-lib/01-api.php 01-api.php.

Errors are managed in to modes. First they are 'declared' and second they are 'raised'.

Declaring error numbers

To declare a possible error call the err()->define function. The first argument is the name of the error known as the error const. The error const has up to 6 parts separated by double-underscore:

1. 'ERROR'
2. type (e.g. 'LIB', 'OBJ', etc.)
3. module/class (e.g. 'API', 'VALIDATION')
4. function name
5. variable name
6. state (e.g. 'NOT_NULL', 'INVALID')

The second argument is the error message. The error messages will be translated if necessary and can include variables using the '%variable%' notation of the i18n subsystem.

Raising particular errors

After you have declared an error like this:

err()->define( 'ERROR__LIB__EXAMPLE', 'An error with %param% occurred.' );

you can raise it like this:

throw Error( ERROR__LIB__EXAMPLE, 'param', 'value', intl_context, previous_exception );

where intl_context is an i18n translation context and previous_exception is a previous exception if any.

Security features

In addition to role-based security we protect from XSRF and SQL-injection attacks.

XSRF protection

To prevent XSRF attacks we configure a session token that must be included in all HTTP POST submissions.

SQL-injection protection

To prevent SQL injection attacks we take care to escape inputs when building SQL strings and/or use parameters with our database API.

Web interface

admin-home.php

The admin-home.php

Notes

Notes for implementers

If you are interested in incorporating this software into your project, here's what you need to know:

Notes for developers

If you're looking to set up a development environment for this project here's what you need to know:

Tasks

TODO

Things to do, in rough order of priority:

• Document system design
• Generate task list
• Allocate tasks to developers

Done

Stuff that's done. Latest stuff on top.

• JE 2015-04-01: created project page