Add support for I2C Realtime Clocks

software/CONFIGURATION.md

@@ -81,11 +81,24 @@ shows the default configuration:
 ```json
 {
     "VOLTS_PER_OCTAVE": 1.0,
+    "RTC_IMPLEMENTATION": "",
+    "UTC_OFFSET_HOURS": 0,
+    "UTC_OFFSET_MINUTES": 0,
 }
 ```
 
+Quantization options:
 - `VOLTS_PER_OCTAVE` must be one of `1.0` (Eurorack standard) or `1.2` (Buchla standard). Default: `1.0`
 
+RTC options:
+- `RTC_IMPLEMENTATION` is one of the following, representing the realtime clock enabled on your module:
+  - `""`: there is no RTC present. (default)
+  - `"ds3231"`: use a DS3231 module connected to the external I2C interface
+  - `"ds1307"`: use a DS1307 module connected to the external I2C interface (THIS IS UNTESTED! USE AT YOUR OWN RISK)
+
+Timezone options:
+- `UTC_OFFSET_HOURS`: The number of hours ahead/behind UTC the local timezone is (-24 to +24)
+- `UTC_OFFSET_MINUTES`: The number of minutes ahead/behind UTC the local timezone is (-59 to +59)
 
 # Accessing config members in Python code
 

software/contrib/README.md

@@ -54,6 +54,14 @@ Recording of CV can be primed so that you can record a movement without missing
 <i>Author: [anselln](https://github.com/anselln)</i>
 <br><i>Labels: sequencer, CV, performance</i>
 
+### Daily Random \[ [documentation](/software/contrib/daily_random.md) | [script](/software/contrib/daily_random.md) \]
+A pseudo-random gate and CV sequencer that uses a realtime clock to generate patterns.
+
+Requires installing and configuring a realtime clock module, connected to EuroPi's external I2C interface for best results.
+
+<i>Author: [chrisib](https://github.com/chrisib)</i>
+<br><i>Labels: sequencer, gate, cv, random, realtime clock</i>
+
 ### DCSN-2 \[ [documentation](/software/contrib/dscn2.md) | [script](/software/contrib/dcsn2.md) \]
 A loopable random gate sequencer based on a binary tree.  Inspired by the Robaux DCSN3
 
@@ -165,6 +173,13 @@ While not technically random, the effects of changing the particle's initial con
 <i>Author: [chrisib](https://github.com/chrisib)</i>
 <br><i>Labels: gate, lfo, sequencer, random, trigger</i>
 
+### Pet Rock \[ [documentation](/software/contrib/pet_rock.md) | [script](/software/contrib/pet_rock.py) \]
+A pseudo-random gate generator that uses the realtime clock to track the phase of the moon as a seed. Based on [Pet Rock by Jonah Senzel](https://petrock.site)
+
+Requires installing and configuring a realtime clock module, connected to EuroPi's external I2C interface for best results.
+
+<i>Author: [chrisib](https://github.com/chrisib)</i>
+<br><i>Labels: sequencer, gate, random, realtime clock</i>
 
 ### Poly Square \[ [documentation](/software/contrib/poly_square.md) | [script](/software/contrib/poly_square.py) \]
 Six independent oscillators which output on CVs 1-6.

software/contrib/daily_random.md

@@ -0,0 +1,27 @@
+# Daily Random
+
+Generates pseudo-random gate and CV patterns based on the current date and time.
+
+## I/O Assignments
+
+- `ain`: not used
+- `din`: external clock input
+- `b1`: not used
+- `b2`: not used
+- `k1`: not used
+- `k2`: not used
+- `cv1`: daily gate sequence (updates at midnight local time)
+- `cv2`: hourly gate sequence (updates at the top of every hour)
+- `cv3`: minute gate sequence (updates at the top of every minute)
+- `cv4`: daily CV sequence (updates at midnight local time)
+- `cv5`: hourly CV sequence (updates at the top of every hour)
+- `cv6`: minute CV sequence (updates at the top of every minute)
+
+## Required Hardware
+
+This script _can_ be used on a normal EuroPi, but will result in highly predictable
+patterns. For best result, connect a Realtime Clock (RTC) to EuroPi's secondary I2C
+header pins, located on the underside of the board.
+
+See [Realtime Clock Installation](/software/realtime_clock.md) for instructions on
+installing and configuring the realtime clock.

software/contrib/daily_random.py

@@ -0,0 +1,144 @@
+from europi import *
+from europi_script import EuroPiScript
+
+from experimental.rtc import clock
+
+import random
+
+
+class Sequence:
+    """
+    A single gate or CV sequence
+    """
+    BASE_SEQUENCE_LENGTH = 16
+
+    def __init__(self, seed):
+        self.index = 0
+        self.regenerate(seed)
+
+    def regenerate(self, seed):
+        random.seed(seed)
+
+        # randomize the length so the majority are 16, but we get some longer or shorter
+        length = self.BASE_SEQUENCE_LENGTH
+        r = random.random()
+        if r < 0.1:
+            length -= 2
+        elif r < 0.25:
+            length -= 1
+        elif r > 0.8:
+            length += 2
+        elif r > 0.75:
+            length += 1
+
+        pattern = []
+        for i in range(length):
+            pattern.append(random.random())
+
+        self.pattern = pattern
+
+    def next(self):
+        self.index = (self.index + 1) % len(self.pattern)
+
+    @property
+    def gate_volts(self):
+        return (int(self.pattern[self.index] * 2) % 2) * europi_config.GATE_VOLTAGE
+
+    @property
+    def cv_volts(self):
+        return self.pattern[self.index] * europi_config.MAX_OUTPUT_VOLTAGE
+
+
+class DailyRandom(EuroPiScript):
+    """
+    Generates a set of pseudo-random gate and CV sequences every day
+
+    This script requires a realtime clock. Please refer to
+    experimental.clocks for supported clocks.
+
+    If no RTC is installed & configured, the default clock will be used,
+    but this will generate the same pattern every time the module is
+    restarted.
+    """
+
+    SEQUENCE_LENGTH = 16
+
+    BITMASKS = [
+        0b101010101010,
+        0b001100110011,
+        0b000111000111,
+        0b111111000000,
+        0b111000111000,
+        0b110011001100,
+        0b010101010101,
+    ]
+
+    def __init__(self):
+        super().__init__()
+
+        self.sequences = [
+            Sequence(0) for cv in cvs
+        ]
+        self.regenerate_sequences()
+
+        self.trigger_recvd = False
+
+        @din.handler
+        def advance_sequence():
+            for s in self.sequences:
+                s.next()
+            self.trigger_recvd = True
+
+        @din.handler_falling
+        def gates_off():
+            for i in range(len(cvs) // 2):
+                cvs[i].off()
+
+    def regenerate_sequences(self):
+        datetime = clock.localnow()
+        year = datetime.year
+        month = datetime.month
+        day = datetime.day
+        hour = datetime.hour
+        minute = datetime.minute
+        second = datetime.second if datetime.second is not None else 0
+        weekday = datetime.weekday if datetime.weekday is not None else 1
+
+        # bit-shift the fields around to reduce collisions
+        # mask: 12 bits
+        # year: 11 bits
+        # month: 4 bits
+        # day: 5 bits
+        # hour: 6 bits
+        # minute: 6 bits
+        seeds = [
+            self.BITMASKS[weekday - 1] ^ year ^ (month << 7) ^ day,
+            self.BITMASKS[weekday - 1] ^ year ^ (month << 6) ^ day ^ ~hour,
+            self.BITMASKS[weekday - 1] ^ year ^ (month << 7) ^ day ^ (hour << 6) ^ minute,
+        ]
+
+        for i in range(len(self.sequences)):
+            self.sequences[i].regenerate(seeds[i % len(seeds)])
+
+    def main(self):
+        last_draw_at = clock.localnow()
+        oled.centre_text(str(last_draw_at).replace(" ", "\n"))
+
+        while True:
+            now = clock.localnow()
+            if now != last_draw_at:
+                self.regenerate_sequences()
+                oled.centre_text(str(now).replace(" ", "\n"))
+                last_draw_at = now
+
+            if self.trigger_recvd:
+                self.trigger_recvd = False
+                for i in range(len(self.sequences)):
+                    if i < len(cvs) // 2:
+                        cvs[i].voltage(self.sequences[i].gate_volts)
+                    else:
+                        cvs[i].voltage(self.sequences[i].cv_volts)
+
+
+if __name__ == "__main__":
+    DailyRandom().main()

software/contrib/menu.py

@@ -29,6 +29,7 @@
     ["Consequencer",      "contrib.consequencer.Consequencer"],
     ["Conway",            "contrib.conway.Conway"],
     ["CVecorder",         "contrib.cvecorder.CVecorder"],
+    ["Daily Random",      "contrib.daily_random.DailyRandom"],
     ["DCSN-2",            "contrib.dscn2.Dcsn2"],
     ["Diagnostic",        "contrib.diagnostic.Diagnostic"],
     ["EgressusMelodiam",  "contrib.egressus_melodiam.EgressusMelodiam"],
@@ -48,6 +49,7 @@
     ["NoddyHolder",       "contrib.noddy_holder.NoddyHolder"],
     ["Pam's Workout",     "contrib.pams.PamsWorkout"],
     ["Particle Phys.",    "contrib.particle_physics.ParticlePhysics"],
+    ["Pet Rock",          "contrib.pet_rock.PetRock"],
     ["Piconacci",         "contrib.piconacci.Piconacci"],
     ["PolyrhythmSeq",     "contrib.polyrhythmic_sequencer.PolyrhythmSeq"],
     ["PolySquare",        "contrib.poly_square.PolySquare"],

software/contrib/pet_rock.md

@@ -0,0 +1,82 @@
+# Pet Rock
+
+A EuroPi clone of [Johan Senzel's Pet Rock](https://petrock.site/).
+
+This script generates pseudo-random gate sequences based on the phase of the moon.
+
+## I/O Assignments
+
+- `din`: external clock input for sequence A
+- `ain`: external clock input for sequence B
+- `b1`: manually advance sequence A
+- `b2`: manually advance sequence B
+- `k1`: speed control for sequence A
+- `k2`: speed control for sequence B
+- `cv1`: primary gate output for sequence A
+- `cv2`: inverted gate output for sequence A
+- `cv3`: end of sequence trigger for sequence A
+- `cv4`: primary gate output for sequence B
+- `cv5`: inverted gate output for sequence B
+- `cv6`: end of sequence trigger for sequence B
+
+Both sequence A and sequence B can be internally clocked by setting the speed using `K1` and `K2`. Turning
+these knobs fully anticlockwise will stop the internal clocks.
+
+## Configuration
+
+Pet Rock can be configured to use different pseudo-random rhythm-generating algorithms. To choose, edit
+`config/PetRock.json` to set the `MOODS` key:
+```json
+{
+    "MOODS": "classic"
+}
+```
+
+- `MOODS` can be one of `classic` (default), `alternate`, or `all`
+
+Depending on the `MOODS` configured, the following algorithms are used, cycling every new moon:
+
+**Classic**
+- ![swords](./pet_rock-docs/swords.png) Plain
+- ![cups](./pet_rock-docs/cups.png) Reich
+- ![shields](./pet_rock-docs/shield.png) Sparse
+- ![pentacles](./pet_rock-docs/pentacle.png) Vari
+
+**Alternate**
+
+These algorithms were implemented in the original Pet Rock firmware, but ultimately not used in the final
+release.
+- ![hearts](./pet_rock-docs/heart.png) Blocks
+- ![spades](./pet_rock-docs/spade.png) Culture
+- ![diamonds](./pet_rock-docs/diamond.png) Over
+- ![clubs](./pet_rock-docs/wands.png) Wonk
+
+**All**
+
+When `"all"` moods are selected, the order is the 4 classic algorithms, followed by the 4 alternate algorithms,
+in the order listed above.
+
+
+### Note on suits
+
+Yes, I'm aware that "shields" isn't a normal Tarot suit. Originally I used "clubs" (an alternative to the
+traditional "wands" suit in most tarot decks). But it seemed weird having 3/4 English card suits used for
+the alternate moods, and then have "shields" tossed-in to fill it out; "shields" is a suit more associated
+with Swiss playing cards.
+
+Since shields and swords are a natural pairing, I swapped things around to have, in my mind, more logical
+groupings. I'm sorry if this decision causes anyone distress.
+
+Additionally, I realize the "pentacle" symbol has some negative associations for some. No offense is meant;
+this is a traditional suit in tarot cards, and felt appropriate for a moon-phase-tracking program. I did
+consider swapping it for its "coins" alternative, but was concerned that a circular or elliptical coin
+motif might be too visually similar to the full & gibbous moon icons.
+
+
+## Required Hardware
+
+This script requires a Realtime Clock (RTC) to EuroPi's secondary I2C header pins,
+located on the underside of the board.
+
+See [Realtime Clock Installation](/software/realtime_clock.md) for instructions on
+installing and configuring the realtime clock.