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:
- 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
- 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.).
- What error was then observed?
- What further effect did it have?
- 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.
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.
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
- 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 Firmware
||Common files that are used to build binary packages for download.|
||Common makefile include files which are used for all devices.|
||Common source code that is used for more than one device, like AES, UART and generic utility code.|
||Base directory for a specific device, starting with
||The bin directory contains the result of a compilation. These files must not be submitted to the repository.|
||This is a temporary directory used for the compilation process and is not stored in the repository.|
||Device specific (software) documentation.|
||Device specific files that are used to build binary packages for download.|
Directory Structure Hardware
||Additional EAGLE libraries for hardware components used by SHC.|
||Base directory for a specific device. The files in this directory typically include:
These are the Make rules you will probably need:
||Build the firmware and fuse files incrementally.|
||Build everything from scratch.|
||Clean up the build and bin subdirectories.|
||Writes the fuse bytes to files.|
||Program the device firmware to your device using AVRDUDE (without fuses).|
||Program the device fuses to your device using AVRDUDE. Handle with care! Wrong fuse setting may trash your microcontroller.|