Steps tried so far: 1) Download the pre-compiled Debian distro from WaveShare site and updating it with Tkinter to match the Debian distro that I got from BeagleBone. 2) Trying to compile the drivers that WaveShare supplies into my distro from BeagleBone. 3) Trying to compile the driver source code for the PCF8563 chip that is available online. 4) Buy a BeagleBoneBlack from Adafruit which comes loaded with Debian already and hope whatever distro that Adafruit supplies has driver module for the PCF8563
Results for approach 1) Trying the pre-compiled distro from Waveshare: The Debian Distro from the WaveShare site interfaced smoothly with the RTC cape. It was a complete SD card image, which I downloaded and installed on an SD card. It booted up and found the LCD screen and had LXDE with about the same desktop configuration as the Debian distro from the BeagleBone site. I was able to execute all of the steps I had previously learned to install the PCF8563 chip as a new device on the i2c bus, it was recognized by the driver and a new rtc device was installed in /dev, I was able to write the date to the rtc and read it back, and the steps from several sites for setting up a service to set the system time from the rtc during bootup all worked. This distro, like the BeagleBone distro, did not have Tkinter. I executed the steps to use apt-get to install Tkinter and they worked fine. I was able to run my Tkinter code. But I found that there is a huge problem in that the file manager freezes and crashes during any "drag and drop" operations!!!
From here, it seems like my options branch into: a) try to figure out if the pcf8563 driver in this distro is somehow a module that I can copy and install into the BeagleBone distro, or b) try to figure out how to fix the drag and drop crashing problem in the WaveShare distro. While looking for module files in the WaveShare distro, the module directory name showed that it seems to be numbered "Bone40" while the distro that I got from BeagleBone is "Bone70" so perhaps there were issues that got fixed between when WaveShare compiled their drivers and when I downloaded Debian from the BeagleBone site.
Some links to sort through later:
A link which might help me with updating the WaveShare distro to fix the drag and drop issue: https://www.debian.org/doc/manuals/debian-faq/ch-uptodate.en.html
Results from approach 2) Try to compile the driver files supplied by Waveshare: I am making a stab at trying to understand the instruction on the Waveshare site for compiling their modules. The document XXX_CAPE_Porting_Drivers.pdf says to do *something* (it's not clear) with the .dts file provided by the site in a zip file of .dts files. It might be that the use of the word "Coding" in the instructions is an incorrect translation from another language, since the instructions seem to be saying just to find the file and place it in a particular location. Also, apparently the instructions cover doing the same driver porting for an i2c driver which makes a little bit of sense since the PCF8563 is on the i2c bus for the BeagleBone, but I'm not sure if there aren't already i2c drivers in my Debian distribution, and if there are I'm not sure if they'd be compatible with whatever RTC driver WaveShare is providing or if Waveshare's RTC driver requires Waveshare's i2c driver only. The results seem to be .dtbo files which have to be placed into certain directories and then a text string which is similar but not exactly the same as the name of each of the .dtbo files gets echoed to some kind of capemanager device similar to how the chip gets installed as a new i2c device. Among other questions this raises, I have to wonder if this is a one-time operation or does it have to be performed on every bootup by some kind of service? There's a hint in section 16 of the document that says that their Angstrom distribution pretty much does this, although the directories discussed don't look like those that I put service scripts into while playing around with Debian. The Section 14 described in the card has a lot of discussion about something called a TF card, and seems to be rather Angstrom-specific, giving me despair that this entire process could be inapplicable to Debian.
http://www.waveshare.com/w/upload/2/20/XXX_CAPE_Porting_Drivers.pdf
.dts apparently stands for device tree source file. There's something called a .dtsi which is the device tree source include file. This is explained in the following very dense tutorial, most of which I still don't get after the acronym expansions:
http://elinux.org/Device_Tree
This seems to be a tutorial specifically addressing what Device Tree is in the context of BeagleBone. It talks about kernel 3.8 which I've seen is what both my official BeagleBone Debian distro is as well as the Waveshare Debian distro. It gets confusing about 1/4 of the way in, but it seems that I need to fully understand what is being discussed at this link if I ever hope to recompile the Waveshare drivers for the Bone70 kernel:
http://elinux.org/BeagleBone_and_the_3.8_Kernel
Interestingly, now that I have begun reading the above links, the driver loading instructions for the original but discontinued cape that I had hoped to get are now making a lot more sense. This shows a step not in the Waveshare instructions which is how to check the event logs for successful load of the device tree overlay. Also the links at the bottom of the page, which previously seemed random, now look like additional tutorials about Device Tree that could help me:
http://elinux.org/CircuitCo:RTC_Cape
Update Jan 31 2016: So far I have been able to compile the .dts files from Waveshare but it hasn't resulted in the pcf8563 chip being recognized or a new rtc being added for it under /dev. Here is the latest new information that I've dug up.
First of all, I've found a gorgeous tutorial on how to compile dts files for BeagleBone, once again on Adafruit. The tutorial is found here:
https://learn.adafruit.com/introduction-to-the-beaglebone-black-device-tree/overview
A pdf of the same tutorial is here:
https://learn.adafruit.com/downloads/pdf/introduction-to-the-beaglebone-black-device-tree.pdf
The above tutorials seemed to help with compiling the dts files from Waveshare. This was despite concerns due to the dts directory from Waveshare zip file explicitly having "Angstrom" in its name. The dts file was compiled to a dtbo file which I copied to /lib/firmware as shown in the adafruit tutorial (but not shown in the Waveshare tutorial, for which none of the kernel directories listed match the ones in my Debian distro), and I was able to echo the module name to the "slots" file in /sys/devices/bone_capemgr.8 and then see that it had been added. However there was no new rtc in /dev. The messages from 'dmesg | tail' all looked good up to a point, it shows the overlay being found and applied, but it still doesn't show the RTC chip being recognized. I tried manually doing the steps to add the pcf8563 to i2c-1 and it instantiated the device the same as it has been but the device still seemed to be unrecognized by any driver.
In a simple world, it should be enough to try restarting the system, but I was pretty sure that would just roll back my overlay installation, and sure enough at the bottom of the Adafruit tutorial it says "We know that restarting the system will cause the overlays to unload" and gives instruction on adding something to a configuration file to cause them to be loaded on every bootup.
Looking at the results from dmesg after manually adding the pcf8563 made me wonder what the 'i2c i2c-1: new_device: Missing parameters' message could mean, particularly since it was followed by the cheerful looking 'i2c i2c-1: new_device: Instantiated device pcf8563 at 0x51' message. The google search for this came up with some good hints but nothing that has lead to a clear 'ah-ha' moment.
Here's a readme about i2c that seems to have four separate hints about what that message could mean, none of them clear. https://www.kernel.org/doc/Documentation/i2c/instantiating-devices
Here's a forum thread with a guy who was having trouble getting his ds1307 RTC to work. It seems like he was missing a module or something, but it's not entirely clear what his problem was or what the resolution was that he found. It's also a little sad that this issue was with a pi and not a BeagleBone. https://github.com/adafruit/adafruit-raspberrypi-linux/issues/2
Possibly a related forum thread on the problem. It seems that the problem was simply that the required modules were not loaded? http://forums.adafruit.com/viewtopic.php?f=50&t=31821
Since it seems like people most often solve problems when trying to interface the ds1307 RTC, I wanted to see what would happen if I did a google search for the ds1307 module. I got more hints at the links below:
Here's the Google search: https://www.google.com/search?q=ds1307+kernel+module
Here's a forum thread started by somebody that's following the Adafruit 1307 tutorial and having trouble getting the module to load. Somebody replies with a bunch of really specific instructions which are a lot like the instructions I saw on another thread, one of which is to get the package for i2c-tools. I'm wondering if this is something that would help me? Sadly, when I did 'apt-get update' and 'apt-get install i2c-tools', I got back 'i2c-tools is already the newest version' meaning I probably already have i2c-tools. https://www.raspberrypi.org/forums/viewtopic.php?p=273354
Here's another tutorial, completely unrelated to the Adafruit one, on adding the Adafruit ds1307 stamp to a BeagleBone. It's a very nicely done tutorial, and it also shows a step of downloading the i2c-tools package. It seems like the author is using a crazy version of linux ("Archlinux Allstar"?), and to do the download he uses a command I've never seen before which is "pacman". http://www.crompton.com/hamradio/BBB_realtime_clock/
So, here is the same Google Search but with the PCF8563. The returned links seem a lot less numerous and helpful. https://www.google.com/search?q=pcf8563+kernel+module
One of the links to the above search is one that I keep hitting which is a list of module files. It doesn't provide any hints about where to find them, but it shows an entire dependency tree that is intriguing. It shows a dependence on i2c-core, which modpobe seems to indicate that I have, but it also shows dependency on rtc-core which comes back from modeprobe as missing, and also rtc-lib which also seems to be missing. http://modules.libres.ch/browse/linux/v2.6.18/powerpc/rtc-pcf8563/
This forum thread has astonishingly complete step-by-step answers to problems interfacing a DS1307 chip to a Raspberry Pi, then for some reason the same treatment is given to somebody trying to interface a PCF8563. On the surface, none of this seems to help me find a kernel module for rtc-pcf8563, but there is so much good information in this link that maybe I'm just missing something in it. https://www.raspberrypi.org/forums/viewtopic.php?t=85683
This link filled me with hope, as it lists a module named "kernel-module-rtc-pcf8563". The fact that the page is all about Angstrom modules was ominous, and indeed on my Debian distro, when I did 'apt-get update' and 'apt-get install kernel-module-rtc-8563' it came back with 'E: Unable to locate package kernel-module-rtc-8563'
http://feeds.angstrom-distribution.org/feeds/v2012.05/ipk/eglibc/armv7a/machine/beaglebone/Packages
Having read the translation, it seems like there is no new information here, but for novelty's sake here is a page from China (also the source of the Waveshare Misc Cape) on interfacing a PCF8563 chip: https://translate.google.com/translate?hl=en&sl=ko&u=http://blog.daum.net/_blog/BlogTypeView.do%3Fblogid%3D0Ps5d%26articleno%3D49%26_bloghome_menu%3Drecenttext&prev=search
Results for approach 3) Trying to compile the driver source code into either the kernel or a kernel module: I have frequently encountered some source code for a driver module for the PCF8563 chip during my web searches. It seems to come from the manufacturer of the chip, which would be Phillips (which was subsequently bought by another company):
https://github.com/jeffegg/beaglebone/blob/master/drivers/rtc/rtc-pcf8563.c
also here: https://github.com/tekkamanninja/linux-beagleboard/blob/master/drivers/rtc/rtc-pcf8563.c
and also here: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/drivers/rtc/rtc-pcf8563.c?id=57d54889cd00db2752994b389ba714138652e60c
Interestingly, there seems to be a slightly different version (which still contains a line returning version 0.4.3). It can be found here:
https://stuff.mit.edu/afs/sipb/contrib/linux/drivers/rtc/rtc-pcf8563.c
and here: http://lxr.free-electrons.com/source/drivers/rtc/rtc-pcf8563.c
The reason why I think this code might be the thing that I want to try to compile is that it seems to have a version number (0.4.3) that is the same as the one shown in log messages from the rtc-pcf8563.ko module for people that already have it in their linux distribution, like as seen at these links:
http://www.boonsanti.com/setting-a-real-time-clock-to-beaglebone-black-with-rtc-pcf8563/
(Note: this is the one where the blogger talks about "Chris Boot's Forked Kernel" and he's working on a Pi) http://www.susa.net/wordpress/2012/06/raspberry-pi-pcf8563-real-time-clock-rtc/
https://groups.google.com/forum/#!topic/beagleboard/YytMAKTdYrE
https://www.raspberrypi.org/forums/viewtopic.php?f=44&t=6994
Aside from that, all I have so far are some links that seem to have helpful general advice on how to compile driver modules. I need to read all of these before I give this approach a try:
A very friendly and hopefully basic tutorial on compiling stuff into Debian: http://www.aboutdebian.com/compile.htm
A basic linux faq about kernel modules. It shows modules in the location where I find them in the BeagleBone distro, but not where the PCF8563 files seem to be in the WaveShare distro (which possibly indicates that WaveShare compiled their drivers into the kernel instead of creating a module): http://www.cyberciti.biz/faq/add-remove-list-linux-kernel-modules/
A very sparse page of information about modules, which includes at the bottom a link to the "all modules" page which shows a rtc-pcf8563 module (although it's not clear if it's the same one that I need): https://wiki.debian.org/Modules
A fairly sparse HowTo on how to compile modules. This plus some other links might give me a starting point to trying my own compilation: http://www.cyberciti.biz/tips/build-linux-kernel-module-against-installed-kernel-source-tree.html
A beginner's article for understanding Make, Configure, and other generic steps in most compilations in Linux. Probably doesn't contain anything about drivers, but could help me get started: http://www.codecoffee.com/tipsforlinux/articles/27.html
Results for approach 4) Buy a BBB preloaded with Debian: Sadly, this didn't pan out as hoped, although there might be some advantages to pursuing this further. First of all, the BBB is half the price of a regular BB, it's only $45 which is basically less than a tank of gasoline. Secondly, it's supposedly faster.
However, it didn't recognize the pcf8563 chip when I plugged it in place of the BeagleBone and didn't seem to have the driver module. It did recognize the LCD7 screen, and came up with an LDXE desktop very similar to my current one except that it had four instead of 2 desktops. However, less than 15 minutes after I started using the BBB, it crashed and wouldn't reboot; apparently the OS in flash memory got corrupted. In the short time that I used it, I noticed that it took three times longer to boot than the BB I've been using, and when I tried to run Python it didn't work despite being found in the executable path. The BBB froze while I was trying to figure out why I wasn't getting the python prompt; trying to run Python might have been the cause for the bricking. I didn't get a chance to try to figure out if it had Tkinter or even what distribution they had shipped.
My initial impression is that having the the OS in flash memory on the BBB is unreliable. I began looking into how to just run the BBB off of the SD drive like I've been doing for the BB. It turns out that this is not very easy, since the BBB will always boot from flash memory if there is something there. Also, the BBB requires you to depress a tiny switch on the board to get it to boot from SD, which is astonishing. Here are some links that I could try to sort out later if I really want to try this:
http://elinux.org/Beagleboard:Updating_The_Software#Image_for_booting_From_microSD
A commenter in this thread seems to think that you only need to push the button the first time you boot from SD, which would be helpful if true: https://groups.google.com/forum/#!category-topic/beagleboard/beaglebone-black/_mOlo6T-70E
Some of the info in this thread, however, seems to contradict the previous one. This link has a lot of info about the uboot utility which seems to be the heart of finding the answer to this question. https://www.element14.com/community/thread/28768/l/beagleboneblackunable-to-boot-u-boot-image-from-sd-card-how-to-do-this?displayFullThread=true
Probably I just need to go through the steps of downloading a new Debian image compatible with BBB and flashing it.
Update Feb 21, 2016: Since getting started on trying to compile the driver module from source code, I've gone down a few different paths. Specifically: 3a) Learning how to compile a simple driver module from the source headers. 3b) Trying to replicate the simple driver compilation with rtc-pcf8563.c, 3c) Learning that rtc-pcf8563.c is provided in the linux source tree, trying to download the source and compile it in place.
Step 3a) Learning how to compile a simple driver module using the source headers: There are several tutorials around the internet on how to compile a simple module called hello.ko which just prints some stuff to the event logs when started and stoppped. The following two links are occasionally unreachable for some reason but from Chrome sometimes a "cached version" is offered. These examples worked perfectly as written.
http://www.cyberciti.biz/tips/build-linux-kernel-module-against-installed-kernel-source-tree.html
http://www.cyberciti.biz/tips/compiling-linux-kernel-module.html
http://www.paulkiddie.com/2009/10/creating-a-hello-world-kernel-module-in-linux/
http://www.lai18.com/content/1641206.html
http://icarus-edward.blogspot.com/2006/09/howto-build-linux-kernel-module.html
The main problem with the above turtorials was that the kernel header package was not named kernel-headers-$(uname -r) but rather linux-headers-$(uname -r). I figured this out using apt-cache search with vaguer and vaguer search terms until I realized what the problem was. Then I used sudo apt-get install to download the source header package and it unzipped it and placed it under /usr/src. The makefile provided by the first link above just worked like a charm and produced a .ko file which could be installed and uninstalled.
Step 3b) Trying to replicate the simple driver compilation with rtc-pcf8563.c: So, I excitedly downloaded rtc-pcf8563.c, and put it in a directory with the makefile from the hello.ko example and changed the name of the target in the makefile. Unfortunately, the C code didn't compile; in particular it barfed on some kind of define named "THIS_MODULE".
At this point I embarked on a big link sausage trying to figure out if I could fix my problems by downloading the entire source. My problem was that when I was doing apt-cache searches, I could find the header package as linux-headers-$(uname -r) but there didn't seem to be a corresponding package for just the source code tree. So, here are some interesting links that probably would fix things for me except none of them were dumbed-down enough for me:
Build the entire kernel? That might work. OMG way too many steps. http://elinux.org/Building_BBB_Kernel
At about the sixth step I was unable to follow what was going on with this otherwise promising tutorial, but I did notice that it employed an apt-get source linux command to get the source. https://wiki.debian.org/HowToRebuildAnOfficialDebianKernelPackage
This link tantalizingly promises that you can build any driver with a simple make command if you install build-essentials. This doesn't seem like it could be true. http://askubuntu.com/questions/177329/how-do-i-install-a-driver-provided-as-source-code
Some more hints about how to use apt-get source. Apparently you can compile directly from apt-get? http://askubuntu.com/questions/28372/how-do-i-get-and-modify-the-source-code-of-packages-installed-through-apt-get
Step 3c) Learning that rtc-pcf8563.c is provided in the linux source tree, trying to download the source and compile this file in place. I mean, presumably the file can be compiled if it's part of the source. For some reason, the next night's searching turned up a magic link that contains step-by-step instructions that even a dummy like myself can follow:
Here's the magic tutorial! Sadly it's got some RPM stuff in it that doesn't apply to my Debian distro, and running make oldconfig led to an hour of banging through menus because I was too impatient to copy over my .config file and the default wasn't even close to right, and I shot myself in the foot in general by skipping a lot of steps and I wasn't even using the right source tree. But this is the closest I've gotten yet to getting a clean compile. It built the .o file for the module, but something called modpost didn't see fit to make it into a .ko file. More on this learning point in later links.
http://www.pixelbeat.org/docs/rebuild_kernel_module.html
Here's the forum thread that led me to the above link. After a lot of the OP getting basic questions from commenters, there are a couple of useful answers in this thread. One of them towards the bottom has a 'make M=' example that I see a lot but which failed to work for me, however maybe I typed something wrong when I tried it.
http://www.linuxquestions.org/questions/linux-kernel-70/rebuilding-a-single-kernel-module-595116/
A link that I've posted to myself before to study, here's somebody basically doing the exact same process of compiling a single driver module, except for a raspberry pi. He downloads build-essential with apt-get, then uses wget to get the source tree, then does a patch which is one of the opaque steps of kernel building for me still. He does the same setup step for .config that the guy from the first link does that I screwed up by skipping, then does a make oldconfig. He does another wget which seems to have to do with getting his module source, then does a make modules_prepare. Then he does a different make command that hasn't worked for me yet but mostly because I keep doing with wrong, which is make -CM= . So this is a good example to try to correlate with the other examples that I've tried now that I've tried them. Just to see if it would help, I tried doing a apt-get install build-essential but I think that it came back already installed or something.
http://blog.remibergsma.com/2013/05/08/adding-a-hardware-clock-rtc-to-the-raspberry-pi/
So, after finding the above information, I first tried to do a compilation while not being very patient. I tried to apt-get the linux source, and for some reason I got a tarball for kernel 3.2 (whereas my distro is 3.8.13-bone70, so kernel 3.8 which was a big change from 3.2). However, 3.2 had all of the same RTC driver directories that the bone70 linux header directories expected, so I thought that I'd give it a try. I didn't do the step of copying my .config file from my existing /boot directory, so make oldconfig was just a mess and I ended up just accepting all of the default choices that it kept offering when it turned out to be a lot. I'm not sure if make prepare and make modules_prepare worked, but I think that they might have. In the end I got it to build the rtc-pcf8563.o file but I couldn't make it do the .ko file. I did a pile of hunting for solutions to the error message that I was getting; now I have a bunch of interesting links that didn't help, and I later learned that my problem was something else altogether.
Next I tried downloading the Debian source directories from Waveshare. The tar file was named with kernel version 3.8.13, and the directory structure that it untar'd looked exactly like what I expected. The download came with an additional directory of config files, for either beagleboard, beaglebone, and something else. I checked the beaglebone config file that came in that directory with the one in my distro and it turned out to be wildly different, and also the config file that came with the Waveshare distro didn't have the pcf8563 enabled which was odd since this was supposed to be a kernel for use with the Waveshare board. The big disappointment is that make prepare bombed out completely. I did a pile more research on what was happening, which seemed to have something to do with the Waveshare distro being set up to use a different cross compiler than what was provided in my Debian distro. A couple of half-hearted attempts to switch over the cross compiler selection in the makefile quickly led to deciding to ditch the Waveshare source altogether.
Next I tried to get the 3.8.18-bone70 source tree. Most of the beaglebone Debian pages end up pointing to a github repository. The troubling thing about those links is that it seemed to be for a 4.1 kernel which I don't even know what that would be in relation to 3.8.18. I fiddled around in the github branch that the beaglebone/4.1 code was in, and eventually found a tag for 3.8.18-bone70, but I could not figure out how to download it with git. The site has a big "Get Zip File" button, so I downloaded that and used 7zip to just completely unzip and untar it (I can't remember why I couldn't untar it on my beaglebone) then transferred the entire 400MB directory to a local directory on my beaglebone. I copied the .config file from my boot directory and updated it to enable the pcf8563 driver. Amazingly, make oldconfig, make prepare, and make modules_prepare all went completely smoothly. The make for scripts/mod didn't seem to do anything, and I got the "MODPOST 0 modules" message but kept going.
make SUBDIRS=drivers/rtc ran to completion, alright! But it still didn't make a .ko file for the rtc-pcf8563 driver, boo! It did make two others, rtc-ds2404.ko and rtc-snvs.ko. I looked for these in the .config file, and found that instead of being set to '=y' in the config file, these two were set to '=m'! I set that for the rtc-pcf8563 driver, tried to do another make and didn't get anything, redid make oldconfig, make prepare, make modules_prepare, and make SUBDIRS=scripts/mod, then did make SUBDIRS=drivers/rtc and it made my rtc-pcf8563.ko file!!!!
Following a couple of the examples that I've been trying for ages to get working, I did a modprobe i2c-tools, but when I did modprobe rtc-pcf8563, it returned with rtc-pcf8563 not found. I tried copying the file to the same directory that the rtc-ds2404.ko and rtc-snvs.ko files were, but it still didn't work. I also tried insmod
Somebody online recommended using modprobe -f to just overcome this error; I eventually further learned that this requires either copying or linking my .ko file into the directory /lib/modules/
It seems that usually people brute-force their way past this by recompiling the whole kernel, but a few links that I've found show how some steps for building Modules.symvers so I thought that I'd give that a try. However, a search of my directory tree revealed that the Debian distro image had come with a Modules.symvers file. I copied it to the top of the downloaded source tree, did the entire build process again, and did not get the warning messages. I copied the new .ko file to the proper location and repeated the steps of depmod -a and modprobe and it installed! Because I had earlier installed the pcf8563 chip onto the i2c bus, the chip was instantly recognized by the driver, /dev/rtc1 was created, and I was able to read the time from it! I then copied the .ko file to the other copy that I've been using of the Debian distro, and when I placed it in /lib/modules/
So, in conclusion, the Debian image distributed by Waveshare is broken, I'm still too stupid to figure out how to use the Device Tree and the .dts files from Waveshare, the source file trees from Waveshare are completely broken, the driver for the PCF8563 that other people seemed to be able to use already comes with the source tree for my Debian distro but it hadn't been compiled and it is still barely clear to me how to download the source tree, once the source tree for my distro was downloaded and the .config file was properly modified, a specific set of make commands could be used to build the driver into a module which is, as hoped, portable to copies of the same distro.
