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 check if the bug in already documented. If this is the case, but you have new information about the problem, add the info there to help find the problem.
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:
- 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
- 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.).
- Result
- What error was then observed?
- What further effect did it have?
- 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 me by mail to discuss 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 by mail!
If you want to implement the change, but are uncertain about the need for it, the specific behavior or the way to implement it, consider contacting me by mail to discuss it. It's better to discuss about the implications first and what other users would like the feature to behave before it is implemented.
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. 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.
And then of course, you support me personally by 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:
|
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. |