# CircuitPython CLUE I Ching Caster ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/090/689/medium800thumb/circuitpython_output.jpg?1588009266) In this guide we will show you how you can use your [Adafruit CLUE](https://www.adafruit.com/product/4500) to consult the ancient Chinese text known as the [I Ching](https://en.wikipedia.org/wiki/I_Ching), or Book Of Change. With a simple shake of your CLUE board, you can tap into the mystic forces of the universe and come up with a "random" hexagram that forms the basis of a reading used to consult the I Ching. So grab a CLUE, load the code, balance your chi, and have some fun! Ommmmmmm. ### Adafruit CLUE - nRF52840 Express with Bluetooth® LE [Adafruit CLUE - nRF52840 Express with Bluetooth® LE](https://www.adafruit.com/product/4500) Do you feel like you just don't have a CLUE? Well, we can help with that - get a CLUE here at Adafruit by picking up this sensor-packed development board. We wanted to build some projects that have a small screen and a lot of sensors. To make it compatible with existing projects, we made... Out of Stock [Buy Now](https://www.adafruit.com/product/4500) [Related Guides to the Product](https://learn.adafruit.com/products/4500/guides) ![Animated GIF showing CLUE board displaying data from the many on-board sensors.](https://cdn-shop.adafruit.com/product-videos/640x480/4500-04.jpg) ![](https://cdn-learn.adafruit.com/assets/assets/000/090/700/medium800/circuitpython_reading_with_text.jpg?1588011755) # CircuitPython CLUE I Ching Caster ## I Ching Summary ![](https://cdn-learn.adafruit.com/assets/assets/000/090/594/medium800/circuitpython_text_banner.jpg?1587591906) The[I Ching](https://en.wikipedia.org/wiki/I_Ching) is an ancient text. As such, there are numerous descriptions of what it is and what it has become. To keep things fun and simple, we are going to use a very brief description here. The I Ching is comprised of 64 separate entries. Each entry is associated with a hexagram along with a collection of text that reads like poetry. Let's cover a few details. ## Yin and Yang The most fundamental basis for the I Ching is the concept of Yin and Yang - the two intertwined forces that drive the universe. Can't have one without the other. Light and dark. Sweet and sour. Etc. A common way to represent Yin and Yang is with line segments like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/078/medium800/circuitpython_yin_yang.png?1585760561) These two lines are put together to create further symbols called trigrams, a stack of 3, and hexagrams, a stack of 6. ## Trigrams and Hexagrams The two lines representing Yin and Yang are put together in groups of 3 to comprise 8 trigrams which are considered to comprise the basic elements, like "Earth" and "Mountain". The trigrams are then stacked in groups of two to create the 64 unique hexagrams. The basis here is essentially binary, 0=Yin and 1=Yang. The prefix "tri" means 3 and "hex" means 6. So the hexagrams are like a 6 bit value (2^6 = 64). They are read from bottom to top, so you end up with something like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/079/medium800/circuitpython_hexagram_breakdown.png?1585761160) This binary interpretation is not really used in the I Ching. But it is useful for our code. We don't need any fancy storage mechanism to correlate a specific hexagram with a given number from 0 to 63 (64 total). We can simply use the binary representation of that number to generate the hexagram. For example, let's say we somehow came up with 42 as our "reading". Then we can do something like: ```python >>> print("0b{:06b}".format(42)) 0b101010 >>> ``` and use each of the bits to generate a corresponding line for the hexagram. Each 0 becomes a dashed line Yin and each 1 becomes a solid line Yang. ## Consulting the I Ching For each of the 64 hexagrams there is an entry in the I Ching with a bunch of vague poetic like text. These 64 entries comprise the I Ching - **it's basically a reference text**. Since the I Ching itself is nothing but a collection of 64 entries, how is it used? To "consult" the I Ching you must come up with a number from 1 to 64. And then you look up the I Ching entry for that hexagram number. While this process should be something intrinsically random, the idea is that **you** should be involved in this randomness and thus give a "reading" that is unique to you. This is referred to a [cleromancy](https://en.wikipedia.org/wiki/Cleromancy). There are approaches that involve shaking a bundle of sticks, flipping coins, etc. But once you have the value, you then just look it up in the I Ching. [I Ching Hexagram Table](http://the-iching.com/hexagram_table) Of course making sense of what the actual words are trying to tell you is another story. Seek out an old mystic living in a cave on a mountain for help. # CircuitPython CLUE I Ching Caster ## CircuitPython on CLUE [CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY**  flash drive to iterate. The following instructions will show you how to install CircuitPython. If you've already installed CircuitPython but are looking to update it or reinstall it, the same steps work for that as well! ## Set up CircuitPython Quick Start! Follow this quick step-by-step for super-fast Python power :) [Download the latest version of CircuitPython for CLUE from circuitpython.org](https://circuitpython.org/board/clue_nrf52840_express/) **Click the link above to download the latest version of CircuitPython for the CLUE.** Download and save it to your desktop (or wherever is handy). ![adafruit_products_CLUE_UF2_Downloaded.png](https://cdn-learn.adafruit.com/assets/assets/000/088/037/medium640/adafruit_products_CLUE_UF2_Downloaded.png?1580840077) Plug your CLUE into your computer using a known-good USB cable. **A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.** Double-click the **Reset** button on the top (magenta arrow) on your board, and you will see the NeoPixel RGB LED (green arrow) turn green. If it turns red, check the USB cable, try another USB port, etc. **Note:** The little red LED next to the USB connector will pulse red. That's ok! If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right! ![adafruit_products_Clue_Reset_NeoPixel_bootloader.png](https://cdn-learn.adafruit.com/assets/assets/000/087/919/medium640/adafruit_products_Clue_Reset_NeoPixel_bootloader.png?1580496467) You will see a new disk drive appear called **CLUEBOOT**. Drag the **adafruit-circuitpython-clue-etc.uf2** file to **CLUE**** BOOT.** ![adafruit_products_CLUE_CLUEBOOT.png](https://cdn-learn.adafruit.com/assets/assets/000/088/042/medium640/adafruit_products_CLUE_CLUEBOOT.png?1580841287) ![adafruit_products_CLUE_drag_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/088/043/medium640/adafruit_products_CLUE_drag_UF2.png?1580841295) The LED will flash. Then, the **CLUEBOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear. If this is the first time you're installing CircuitPython or you're doing a completely fresh install after erasing the filesystem, you will have two files - **boot\_out.txt** , and **code.py** , and one folder - **lib** on your **CIRCUITPY** drive. If CircuitPython was already installed, the files present before reloading CircuitPython should still be present on your **CIRCUITPY** drive. Loading CircuitPython will not create new files if there was already a CircuitPython filesystem present. That's it, you're done! :) ![adafruit_products_CLUE_CIRCUITPY.png](https://cdn-learn.adafruit.com/assets/assets/000/088/044/medium640/adafruit_products_CLUE_CIRCUITPY.png?1580841453) # CircuitPython CLUE I Ching Caster ## Code The code for the CLUE I Ching Caster is listed below. You can copy it out and save it to a local file. Once you've done that, you can save the file as `code.py` in your **CIRCUITPY** folder and it will run automatically when powered up or reset. You'll also need to grab the font file **christopher\_done\_24.bdf**. [christopher_done_24.bdf](https://github.com/adafruit/Adafruit_Learning_System_Guides/raw/master/CLUE_I_Ching/christopher_done_24.bdf) You **CIRCUITPY** folder should look something like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/593/medium800/circuitpython_Screenshot_from_2020-04-22_14-24-32.png?1587590702) ## Libraries You'll need to make sure the following libraries are installed in your **CIRCUITPY/lib** folder: - adafruit\_apds9960 - adafruit\_bitmap\_font - adafruit\_bus\_device - adafruit\_display\_text - adafruit\_register - adafruit\_bmp280.mpy - adafruit\_clue.mpy - adafruit\_lis3mdl.mpy - adafruit\_lsm6ds.mpy - adafruit\_sht31d.mpy - neopixel.mpy You can find more info on downloading and installing libraries here: [CircuitPython Libraries](https://circuitpython.org/libraries) When you're done, your **CIRCUITPY/lib** folder should look like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/592/medium800/circuitpython_Screenshot_from_2020-04-22_14-17-53.png?1587590290) https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE/CLUE_I_Ching/code.py ## Usage Here's how to use. - Save the program as **code.py** - Press **RESET** - Should see screen that say " **SHAKE FOR READING**" ![circuitpython_demo_thumb1.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/690/medium640/circuitpython_demo_thumb1.jpg?1588009417) - You should hear a little melody play - The screen will change to " **PRESS BUTTON TO SEE**" ![circuitpython_demo_thumb2.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/691/medium640/circuitpython_demo_thumb2.jpg?1588009469) - Once you press either **A** or **B** button, you should see your hexagram. - If you want to try again, press **RESET** to start over. ![circuitpython_demo_thumb3.jpg](https://cdn-learn.adafruit.com/assets/assets/000/090/692/medium640/circuitpython_demo_thumb3.jpg?1588009523) ## Customizing There are various setting you can change at the top of the code. Look for these lines: ```python #--| User Config |------------------------------- BACKGROUND_COLOR = 0xCFBC17 HEXAGRAM_COLOR = 0xBB0000 FONT_COLOR = 0x005500 SHAKE_THRESHOLD = 20 MELODY = ( (1000, 0.1), # (freq, duration) (1200, 0.1), (1400, 0.1), (1600, 0.2)) #--| User Config |------------------------------- ``` You can change the colors, the shake threshold, as well as the little melody that plays. ## A Note On Translation The original text of the I Ching was written in ancient Chinese. The translation into English used here is based on the text by Kerson and Rosemary Huang (ISBN 978-0894803192). # CircuitPython CLUE I Ching Caster ## Drawing the Hexagram Let's go in to some detail about the approach taken to draw the hexagram. This is a handy little trick that maybe you can reuse in one of your projects. It uses a very simple and tiny sprite sheet [Bitmap](https://learn.adafruit.com/circuitpython-display-support-using-displayio/bitmap-and-palette) to source the two basic line symbols used to generate the hexagram. These are then used in a [TileGrid](https://learn.adafruit.com/circuitpython-display-support-using-displayio/tilegrid-and-group) to generate the actual hexagram. To render this large on the display, the displayio [Group](https://learn.adafruit.com/circuitpython-display-support-using-displayio/group)'s **scale** feature is used. ## Sprite Sheet For a more in depth overview of what a sprite sheet is, see this section of the displayio guide: [Sprite Sheet](https://learn.adafruit.com/circuitpython-display-support-using-displayio/sprite-sheet) Look again at the two lines that comprise the hexagram. They are very basic - just a line and dashed line. We can represent these with a simple bitmap like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/086/medium800/circuitpython_sprite_sheet.png?1585784023) This bitmap is only 11 pixels wide by 4 pixels high. Each blue square is a pixel. The two blank lines are there for padding. The width was chosen for basic aesthetic reasons, generating a nice overall aspect ratio for the lines. This bitmap is so simple that it is generated programmatically. That's what these lines of code are doing: ```python for x in range(11): sprite_sheet[x, 0] = 1 # - - 0 YIN sprite_sheet[x, 1] = 0 sprite_sheet[x, 2] = 1 # --- 1 YANG sprite_sheet[x, 3] = 0 sprite_sheet[5, 0] = 0 ``` ## Using a Tile Grid for the Hexagram The sprite sheet can then be used along with a TileGrid to generate any of the 64 hexagrams. The TileGrid will be 1 column by 6 rows - one row for each line of the hexagram. Each cell is 11 pixels wide by 2 pixels high, corresponding to one of the symbols from the sprite sheet. Then it's a simple matter of setting the source index for each cell of the TileGrid to point to one of the two available bitmaps from the sprite sheet. For example, to make the 3rd line down a dashed (Yin) symbol, we would do something like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/084/medium800/circuitpython_sheet_grid.png?1585783735) To generate the entire hexagram we just set each cell in the TileGrid to a source from the sprite sheet. Like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/090/121/medium800/circuitpython_hex_tilegrid.png?1585870909) Some thought has been put into the arrangement of the sprite sheet. By making the dashed (Yin) symbol be first, we can then generate a hexagram from any integer 0 to 63 (64 total) by simply using each of its bits to set the TileGrid's sources. In the example above, that would be **0b100101 = 37**. Remember, the least significant bit is on the bottom. That general approach is what is being down in the `show_hexagram` function: ```python def show_hexagram(number): for i in range(6): tile_grid[5-i] = (number >> i) & 0x01 ``` ## Using Scale to Embiggen In its raw form, the sprite sheet is only 11 pixels wide by 4 pixels high. The hexgram created from the sprite sheet ends up being 11 pixels wide by 12 pixels high. That's pretty small. So how can we make it bigger on the display? By using `scale`. The `scale` parameter is an option for the [displayio.Group](https://circuitpython.readthedocs.io/en/latest/shared-bindings/displayio/Group.html) class. It is used as a multiplier when rendering the contents of the Group. Every pixel is drawn "scale" number of times. So if scale=3, then every 1 pixel would become 3x3 pixels on the display. A scale factor of 10 is used for the hexagram, which is specified in this line of code: ```python hexagram = displayio.Group(max_size=1, x=60, y=15, scale=10) ``` So the 11x12 hexagram ends up being drawn at an actual size of 110x120 pixels. There's no fancy smoothing done, which can lead to a very coarse look to the scaled up bitmap. However, since our shapes are blocky rectangles, this works out just fine. ## Featured Products ### Adafruit CLUE - nRF52840 Express with Bluetooth® LE [Adafruit CLUE - nRF52840 Express with Bluetooth® LE](https://www.adafruit.com/product/4500) Do you feel like you just don't have a CLUE? Well, we can help with that - get a CLUE here at Adafruit by picking up this sensor-packed development board. We wanted to build some projects that have a small screen and a lot of sensors. To make it compatible with existing projects, we made... Out of Stock [Buy Now](https://www.adafruit.com/product/4500) [Related Guides to the Product](https://learn.adafruit.com/products/4500/guides) ## Related Guides - [Introducing Adafruit CLUE](https://learn.adafruit.com/adafruit-clue.md) - [Digital Egg Drop Experiment with CLUE](https://learn.adafruit.com/egg-drop-clue.md) - [No-Touch Hand Wash Timer for Circuit Playground Express and CLUE](https://learn.adafruit.com/no-touch-hand-wash-timer-for-cpx-and-clue.md) - [CLUE Text Telephone Transmitter](https://learn.adafruit.com/clue-teletype-transmitter.md) - [Using the Bluefruit Dashboard with Web Bluetooth in Chrome](https://learn.adafruit.com/bluefruit-dashboard-web-bluetooth-chrome.md) - [Creative Inspiration Activity Generator](https://learn.adafruit.com/creative-inspiration-activity-generator.md) - [PyBadger Event Badge](https://learn.adafruit.com/pybadger-event-badge.md) - [Karel The Robot In CircuitPython](https://learn.adafruit.com/karel-the-robot-in-circuitpython.md) - [CLUE Rock, Paper, Scissors Game using Bluetooth](https://learn.adafruit.com/rock-paper-scissors-circuitpython.md) - [ulab: Crunch Numbers fast in CircuitPython](https://learn.adafruit.com/ulab-crunch-numbers-fast-with-circuitpython.md) - [CLUE Sensor Plotter in CircuitPython](https://learn.adafruit.com/clue-sensor-plotter-circuitpython.md) - [Cluetooth Scanner](https://learn.adafruit.com/cluetooth-scanner.md) - [BLE Thermal "Cat" Printer with CircuitPython](https://learn.adafruit.com/ble-thermal-cat-printer-with-circuitpython.md) - [CLUE Slim Case](https://learn.adafruit.com/clue-slim-case.md) - [Pyloton: CircuitPython Cycling Computer](https://learn.adafruit.com/pyloton.md) - [CLUE Vertical Garden Weather Visualizer](https://learn.adafruit.com/clue-vertical-garden-weather-visualizer.md)