adafruit / adafruit_circuitpython_ds1307 Goto Github PK

View Code? Open in Web Editor NEW

7.0 21.0 10.0 591 KB

CircuitPython drivers for the DS1307 realtime clock.

License: MIT License

Python 100.00%

circuitpython hacktoberfest

adafruit_circuitpython_ds1307's Introduction

Introduction

This is a great battery-backed real time clock (RTC) that allows your microcontroller project to keep track of time even if it is reprogrammed, or if the power is lost. Perfect for datalogging, clock-building, time stamping, timers and alarms, etc. The DS1307 is the most popular RTC - but it requires 5V power to work.

The DS1307 is simple and inexpensive but not a high precision device. It may lose or gain up to two seconds a day. For a high-precision, temperature compensated alternative, please check out the DS3231 precision RTC. If you do not need a DS1307, or you need a 3.3V-power/logic capable RTC please check out our affordable PCF8523 RTC breakout.

Dependencies

This driver depends on:

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-ds1307

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-ds1307

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .venv
source .venv/bin/activate
pip3 install adafruit-circuitpython-ds1307

Usage Notes

Of course, you must import the library to use it:

import board
import adafruit_ds1307
import time

All the Adafruit RTC libraries take an instantiated and active I2C object (from the board library) as an argument to their constructor. The way to create an I2C object depends on the board you are using. For boards with labeled SCL and SDA pins, you can:

import board

Now, to initialize the I2C bus:

i2c = board.I2C()

Once you have created the I2C interface object, you can use it to instantiate the RTC object:

rtc = adafruit_ds1307.DS1307(i2c)

To set the time, you need to set datetime to a time.struct_time object:

rtc.datetime = time.struct_time((2017,1,9,15,6,0,0,9,-1))

After the RTC is set, you retrieve the time by reading the datetime attribute and access the standard attributes of a struct_time such as tm_year, tm_hour and tm_min.

t = rtc.datetime
print(t)
print(t.tm_hour, t.tm_min)

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

adafruit_circuitpython_ds1307's People

Contributors

Stargazers

Watchers

Forkers

tannewt mrmcwethy sommersoft ajmartel kattni demophoon akrduino jepler mikejc58 coplate

adafruit_circuitpython_ds1307's Issues

Please add version and repo metadata. Thank you!

For this module to work with the upcoming circup utility (see https://github.com/ntoll/circup), there needs to be two bits of metadata expressed as "dunder" objects within the module.

Specifically, circup looks for something like the following:

__version__ = "1.2.3"
__repo__ = "https://github.com/adafruit/SomeLibrary.git"

The __version__ should be a correct semantic-version value (see: https://semver.org/).

The __repo__ should be the HTTPS URL used for cloning this repository.

You can see an example of this behaviour in an existing project here.

Please don't hesitate to ping me if you have any questions. Thank you! 🐍 ❤️ 👍

cc/@ladyada

Install should require Blinka

Not set to install Blinka in setup.py

Example day-of-week string indexing is off-by-one in many repos

In examples/ds1307_simpletest.py, the list of strings used to expand the integer time.struct_time.tm_wday value appears to defined using the C convention (Sunday=0), rather than the Python convention (Monday=0); see https://docs.python.org/3/library/time.html#time.struct_time

A quick search reveals this error in several other repos:

Seconds are returned incorrectly.

Line 271 should be:
second=_bcd2bin(buffer[0] & 0x7F),

Missing Type Annotations

There are missing type annotations for some functions in this library.

The typing module does not exist on CircuitPython devices so the import needs to be wrapped in try/except to catch the error for missing import. There is an example of how that is done here:

try:
    from typing import List, Tuple
except ImportError:
    pass

Once imported the typing annotations for the argument type(s), and return type(s) can be added to the function signature. Here is an example of a function that has had this done already:

def wrap_text_to_pixels(
    string: str, max_width: int, font=None, indent0: str = "", indent1: str = ""
) -> List[str]:

If you are new to Git or Github we have a guide about contributing to our projects here: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

There is also a guide that covers our CI utilities and how to run them locally to ensure they will pass in Github Actions here: https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/check-your-code In particular the pages: Sharing docs on ReadTheDocs and Check your code with pre-commit contain the tools to install and commands to run locally to run the checks.

If you are attempting to resolve this issue and need help, you can post a comment on this issue and tag both @FoamyGuy and @kattni or reach out to us on Discord: https://adafru.it/discord in the #circuitpython-dev channel.

The following locations are reported by mypy to be missing type annotations:

adafruit_ds1307.py:97
adafruit_ds1307.py:117

ValueError: Unable to find DS1307 at i2c address 0x68.

if i 'i2c.scan()' i can see the ds1307 at 0x68 however the last command to setup the rtc fails with an unable to find DS1307 at i2c address ox68 - any help or points greatly appreciated!

Adafruit CircuitPython 3.1.2 on 2019-01-07; Adafruit ItsyBitsy M4 Express with samd51g19

import busio
import adafruit_ds1307
import time
from board import *
myI2C = busio.I2C(SCL, SDA)
rtc = adafruit_ds1307.DS1307(myI2C)
Traceback (most recent call last):
File "", line 1, in
File "adafruit_ds1307.py", line 85, in init
ValueError: Unable to find DS1307 at i2c address 0x68.

DisplayIO Example Wanted

Add a Basic DisplayIO Based Example

We would like to have a basic displayio example for this library. The example should be written for microcontrollers with a built-in display. At a minimum it should show a Label on the display and update it with live readings from the sensor.

The example should not be overly complex, it's intended to be a good starting point for displayio based projects that utilize this sensor library. Try to keep all visual content as near to the top left corner as possible in order to best fascilitate devices with small built-in display resolutions.

The new example should follow the naming convention examples/libraryname_displayio_simpletest.py with "libraryname" being replaced by the actual name of this library.

You can find an example of a Pull Request that adds this kind of example here: adafruit/Adafruit_CircuitPython_BME680#72

We have a guide that covers the process of contributing with git and github: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

If you're interested in contributing but need additional help, or just want to say hi, feel free to join the Discord server to ask questions: https://adafru.it/discord