Contributing Bug Reports + Fixes

If you want to help the project by contributing bug reports or bugfixes, please do it as follows:

1. Check if bug is already known!

If you find a possible bug, look into the open issues on GitHub and in the forums and check if the bug in already documented. If this is the case, but you have new information about the problem, add the info or discuss it there.

2. If uncertain, ask in the forums!

If you're uncertain if you may have done something wrong, feel free to ask in the forums. The discussion often helps to understand how something was meant to use, how something is typically solved by others, or on the other hand makes it clear why something may be too complicated to use (so we can optimize it).

3. Creating a bug ticket

If you're pretty sure it's a bug, create a new issue on GitHub and label it with bug and other matching labels. When you found a trivial bug that e.g. can be understood and fixed by only one line of code, mentioning the necessary change is sufficient. If it's not so trivial, the description should contain:

  1. Preconditions
    • used smarthomatic devices and firmware / software versions
    • E2P configuration (if not default and potentially related)
    • When related to FHEM: OS, perl an FHEM version
    • Bug in E2P editor: OS and Java version
  2. Actions
    • What did you or the devices do right before the error occurred?
    • Write it down as a list of single steps.
    • Be specific (write down used messages etc.).
  3. Result
    • What error was then observed?
    • What further effect did it have?
  4. Expectation
    • What did you expect to happen instead?

4. Create a pull request

If you already analyzed the bug and found the root cause, write it into the ticket, or fix it and create a pull request for the develop branch including the full description as listed above. If you create a pull request, only include the bugfix and nothing else.

Contributing Improvements, Optimizations and Features

If you've an idea possibly needful to other users and would like it to see it in the official versions, proceed as follows:

1. Check design guidelines

If you're not familiar with them, read about design guidelines, features in detail and the communication protocol to learn the basic ideas, concepts and goals of smarthomatic. Check if your idea fits into these general concepts.

2. Change requests

If you have a change request (optimization, logical completion of existing concepts or a (smaller) new feature), you can either ask for it in the forums or implement it and create a pull request against the develop branch containing the change.

Please describe the use case the change is necessary for. Features rarely used or only used by a small amount of users are not likely to be included, so please describe why the additional functionality and complexity is helpful for most of the users. If you want to remove functionality, describe why you think it's not needed by most of the users.

If you provide a pull request, only include one single change at a time (different files may be affected), and don't combine it with other functional changes / optimizations / bugfixes.

3. If uncertain, ask in the forums!

If you want to implement the change, but are uncertain about the need for it, the specific behavior or the way to implement it, discuss it in the forums. It's better to discuss about the implications first and what other users would like the feature to behave before it is impemented.

4. Complex changes, contradictory concepts or ideas not well-thought-out yet

If the change is only a rough idea or contradicts to basic concepts of smarthomatic, but you think it nevertheless makes sense to evolve smarthomatic in this direction, you can also ask me personally via e-mail or private mail in the forums. It might be unclear at first if or when such changes can be made, but they could be interesting on the long term nevertheless.

Other ways to contribute to the project

If you build up devices, you could help to correct the wiki assembly instructions. If something is wrong in there or you find a better way to describe things, just change it.

In the forums, you maybe can help answer questions from others. If you describe your use cases, it may help other users to find new ways to use their smarthomatic devices.

And then of course, you support me personally by buying hardware from the smarthomatic shop or a donation via PayPal or flattr. This always motivates me to continue spending time on the project and to develop it further.

Development Software

If you want to change the firmware or hardware or create new devices, you need additional software as follows. It's all open source or free to use (for personal use).

Build Environment for Software Development

As reference development IDE, WinAVR is used (currently in version 20100110, but others should also work). WinAVR comes with a simple editor and includes the popular GCC compiler and a Make environment. If you don't want to use WinAVR, or you want to work on another operating system than Windows, you can use whatever you want, as long if compatibility allows it. A Linux machine is used for the nightly builds available on this website, so compilation on Linux should be no problem.

Hardware Development

The layout editor EAGLE from CadSoft is used for development of the schematics and PCB layouts for the hardware. Whenever possible, a one- or two-sided PCB not bigger than 4 x 3.2 inch is created to stay within the limits of the Light and Freeware edition of EAGLE.

Version Control and Repository

GIT is used for version control for both software (firmware source code) and hardware (schematics, layouts) files. The smarthomatic repository is hosted on GitHub and contains both firmware source code and hardware files. Remember that firmware and hardware have different licenses.

Firmware binaries are not stored in the repository, but are available for download on this website.

Branching Model and Version Naming Conventions

Branching is done as described here (optional branches are not used if not needed). Versioning is only done by using Git tags with names as described here. These are the most important rules:

  • The master branch is for stable production releases only and lives forever. Every commit in the master branch is immediately tagged in the format vX.Y.Z (without suffix) and is a stable production release.
  • The develop branch is the main integration branch for developing new features and lives forever. No additional tags are created (but tags from master branch are merged back). Merging takes place from and to the master branch.
  • A release branch named release[-vX.Y.Z] may be created with vX.Y.Z being the upcoming new release version (not the version that the branch is created from). Tagged versions are named "vX.Y.Z-(alpha|beta|rc).N" only (e.g. v1.2.0-rc.1 or v1.3.1-alpha.4). Only one release branch without a version suffix is used as long as only one release is prepared at one time.
  • A hotfix branch named hotfix-vX.Y.Z may be created with vX.Y.Z being the upcoming new release version (not the version that the branch is created from). Tagged versions (if needed) are named "vX.Y.Z-rc.N" only (e.g. v1.2.1-rc.1). The hotfix branch is deleted after it is integrated into master.
  • A feature branch may be created for developing a feature outside the develop branch. These branches are named feature-NAMEOFFEATURE. After integration to the develop branch, the feature branch is deleted. There are no tagged versions in a feature branch.
  • Automatic builds are done from the master branch for every tagged version (not head, but this should not differ anyway).
  • At the develop branch, automatic builds are done at HEAD every day, but uploaded to the builds list on the website only if there were changes which impacted the resulting binaries.

Directory Structure

Directory Structure Firmware

Directory Content
extra Common files that are used to build binary packages for download.
makefile_common Common makefile include files which are used for all devices.
src_common Common source code that is used for more than one device, like AES, UART and generic utility code.
rfm12 RFM12 library
shc_{devicename} Base directory for a specific device, starting with shc_.
shc_{devicename}\bin The bin directory contains the result of a compilation. These files must not be submitted to the repository.
shc_{devicename}\build This is a temporary directory used for the compilation process and is not stored in the repository.
shc_{devicename}\doc Device specific (software) documentation.
shc_{devicename}\extra Device specific files that are used to build binary packages for download.

Directory Structure Hardware

Directory Content
lib Additional EAGLE libraries for hardware components used by SHC.
{devicename} Base directory for a specific device. The files in this directory typically include:
  • {devicename}.sch (schematics)
  • {devicename}.brd (board layout)
  • backup files *.s#? and *.b#? must not be submitted to the repository
  • mask.png (the layout mask)
  • placing.png (showing where to put which component)
  • datasheets.txt (links to datasheets)

Make Rules

These are the Make rules you will probably need:

Command Purpose
make Build the firmware and fuse files incrementally.
make all Build everything from scratch.
make clean Clean up the build and bin subdirectories.
make fuse Writes the fuse bytes to files.
make program Program the device firmware to your device using AVRDUDE (without fuses).
make program_fuses Program the device fuses to your device using AVRDUDE. Handle with care! Wrong fuse setting may trash your microcontroller.