Repository layout

[Matthijs Kooijman]

Hey folks,

I had a look over the repository to see what can be cleaned up or should
be moved. Here's what I found in the current repo, along with where I
think it should end up.

trunk/source/
This contains the firmware from trunk, which hasn't seen any
development for a long time. All changes here seem to have been
merged back into rfmsrc/, so this can be deleted.

trunk/playground/
This contains a universal AVR bootloader, which I don't think is
really relevant anymore. Let's delete it.

trunk/doc/
This contains documentation about the hardware and development
process, which still largely relevant.

tools/hr20cmd/
This seems to be a commandline tool that talks to the openhr20
firmware through a serial port connection. It's mostly a
convenience wrapper for serial commands. I'm not sure how
useful this still is (I'd rather have a python script for
something like this anyway). If we keep this, we could perhaps
put it in its own repository, or just keep in in tools/hr20cmd
in the new repo?

branches/before_refactoring_1/
This is an ancient branch that seems to have seen only one
commit. Can be deleted.

rfmsrc/bug_test/
This seems to be some test code that doesn't seem relevant to me
anymore.

rfmsrc/bin/
This contains just a README. The directory can be deleted (and
autocreated by the Makefile if needed) and the info from the
README should be integrated somewhere else.

rfmsrc/common/
This contains some source code common to the "master" and
"OpenHR20" firmwares. This is rather generic code, like RS485,
protocol, RFM hardware code, EEPROM access code, etc.

rfmsrc/doc/
This contains mostly documentation about the RFM protocol used
and the various was to connect the RFM hardware to the HR
hardware. It also contains the hardware design for the master
board and the expansion board.

I guess we should just keep this around as-is. A bit
more consistency and some cleanup wouldn't hurt, but that's
probably more work than it's worth right now.

rfmsrc/frontend/
This is a PHP webapplication that can probably be used to view
info and configure the thermostats. It talks to the thermostats
using a separate daemon, also written in PHP, that talks through
the serial port to the master board (and perhaps also to
thermostats directly?)

This should certainly go into a separate repository.

rfmsrc/master
This is the firmware for the master board. I'm wondering if this
should stick around here, or be put into a separate repository?
The downside of the latter is that the common files can no
longer be shared, of course.

rfmsrc/OpenHR20
This is the actual OpenHR20 firmware for the thermostats. This
should probably become the root of this repository, or if we
keep the master code in here too, remain a subdir.

So, what's there to keep?
- Documentation. This should be put together in the main repo for now.
See below about next steps for documentation.
- The main firmware code. This should just stay in the main repo.
- The master firmware code. I'm inclined to move this into a separate
repo?
- The PHP frontend, this should go into a separate repo.

Thoughts?

Documentation
-------------
I think it would be good to collect all info that's floating around in
a central place. I'm thinking to either use the wiki on github, or
just keep the docs in markdown format in the repository itself. A wiki
might be easier for others to edit, though having documentation changes
go through the usual pullrequest / review process might be good as well.
Any thoughts?

Other resources
---------------
http://www.mikrocontroller.net/articles/Heizungssteuerung_mit_Honeywell_HR20
Contains some documentation about the implementation process, as
well as (seemingly) complet documentation about the serial
protocol implemented by OpenHR20.
http://www.cornelius-consult.de/hr20_doc.txt
Some notes about the HR20 hardware and original firmware.
http://piontecsmumble.wordpress.com/?s=openhr20
Some tutorials about setting up OpenHR20, the master board and
the PHP frontend.
https://www.smarthomatic.org/wiki/doku.php?id=hr25_thermostat
Some info about opening up the HR25 and connecting an ICSP
header (to allow programming through ICSP instead of JTAG).
https://sites.google.com/site/slangey/misc/honeywell-hr25
Some hardware documentation about the HR-25. Also has some info
on the HR-30.

There's also a PNG of the HR20 schematic available. Does anyone happen
to have the eagle files for that lying around? I _think_ I didn't see
them anywhere...

Gr.

Matthijs

[Tomas Kopal]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Matthijs,

looks like pretty damn good summary, well done :-).
Few comments inline:

The PHP app does not talk directly to the thermostats, it communicates
with the master only, via serial line. There is no support for RFM radio
in php, that's the job of the master, and master only.

>
> rfmsrc/master
> This is the firmware for the master board. I'm wondering if this
> should stick around here, or be put into a separate repository?
> The downside of the latter is that the common files can no
> longer be shared, of course.
>
> rfmsrc/OpenHR20
> This is the actual OpenHR20 firmware for the thermostats. This
> should probably become the root of this repository, or if we
> keep the master code in here too, remain a subdir.
>
> So, what's there to keep?
> - Documentation. This should be put together in the main repo for now.
> See below about next steps for documentation.
> - The main firmware code. This should just stay in the main repo.
> - The master firmware code. I'm inclined to move this into a separate
> repo?
> - The PHP frontend, this should go into a separate repo.
>
> Thoughts?

I am not directly against separating some parts to their own
repositories, but they needs to be very closely tied together. Not sure
how that works with git/github, if there is a way, fine. Otherwise, I
would prefer to keep them all in one repo and just put them in separate
folders, as is now.
Basically, coupling between php and master is the serial protocol. Not
sure we can directly share code here, but change in protocol on one side
breaks the other, so the versions needs to be synchronized to some
extent. Maybe some runtime handshake with protocol version could be
implemented to make sure we don't get out of sync (in case of separate
repos)?
Coupling between master and regulator is much closer, via shared code.
While I do not really like the way it is done now (by #include of a cpp
file from "common" directory), I still believe that code sharing (where
appropriate) is good, and we should try hard to keep it. Static library
is probably not an option here, as we have different MCU in master and
regulator...

>
> Documentation
> -------------
> I think it would be good to collect all info that's floating around in
> a central place. I'm thinking to either use the wiki on github, or
> just keep the docs in markdown format in the repository itself. A wiki
> might be easier for others to edit, though having documentation changes
> go through the usual pullrequest / review process might be good as well.
> Any thoughts?

I think that review process on docs is almost as important as on the
code. I believe there are some ways to do reviews on wiki changes,
however that may not be available on github.
Other option would be to have the docs in git, and "export" it to the
wiki from there.
I believe though, that the docs should be all converted to some common
"source" format, which can be used to generate others (pdfs and html for
sure).

>
> Other resources
> ---------------
>
http://www.mikrocontroller.net/articles/Heizungssteuerung_mit_Honeywell_HR20
> Contains some documentation about the implementation process, as
> well as (seemingly) complet documentation about the serial
> protocol implemented by OpenHR20.
> http://www.cornelius-consult.de/hr20_doc.txt
> Some notes about the HR20 hardware and original firmware.
> http://piontecsmumble.wordpress.com/?s=openhr20
> Some tutorials about setting up OpenHR20, the master board and
> the PHP frontend.
> https://www.smarthomatic.org/wiki/doku.php?id=hr25_thermostat
> Some info about opening up the HR25 and connecting an ICSP
> header (to allow programming through ICSP instead of JTAG).
> https://sites.google.com/site/slangey/misc/honeywell-hr25
> Some hardware documentation about the HR-25. Also has some info
> on the HR-30.
>
> There's also a PNG of the HR20 schematic available. Does anyone happen
> to have the eagle files for that lying around? I _think_ I didn't see
> them anywhere...
>
> Gr.
>
> Matthijs
>

Haven't found them either. When I was documenting my HR-25 radio
connection, I did it in bitmap editor, as I was too lazy to redraw the
schematcis :-).
However, as I wrote above for documentation formats, I would again vote
for something open, and in this case also non-binary, so it can be more
easily kept in source control. I know Eagle is quite common, popular,
and even have a "free" version, but it's still closed application and
that could prevent some people from contributing... Ideal would be
format which can be opened (and saved) in multiple programs, like KiCad,
Eagle, Pads, etc., but I do not think that exists.


Other than that, I agree with the changes, they are much needed (and
long overdue ;-) ).

Thanks

Tomas

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.15 (GNU/Linux)

iD8DBQFUMljxNPOQYEFxTnMRAj3fAJsG1d8i9yQM+9xmtI9L+405m34HQQCgle5E
rCJY8IOi3weXT0RSqw67i3c=
=juyb
-----END PGP SIGNATURE-----