From 5c9f072ed44d262f93b93aacd1cbf2386673151c Mon Sep 17 00:00:00 2001 From: besna_shnita Date: Tue, 16 Sep 2025 10:16:19 +0000 Subject: [PATCH] Update Readme.md --- Readme.md | 258 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 143 insertions(+), 115 deletions(-) diff --git a/Readme.md b/Readme.md index a0591cc..aa6f04d 100644 --- a/Readme.md +++ b/Readme.md @@ -17,6 +17,144 @@ show notifications, display the weather, monitor stuff, show a clock, serve a we --- +### Table of Contents + +1. [Bill of Materials](#bill-of-materials) +2. [Assembly Instructions](#assembly-instructions) + * [Body](#body) + * [Buttons](#buttons) + * [OLED Display](#oled-display) + * [Buzzer](#buzzer) + * [Battery Setup](#battery-setup) +3. [Schematics](#schematics) +4. [Demo Code Explanation](#demo-code-explanation) + * [Getting Started](#getting-started) + * [Project Structure](#project-structure) + * [What the Code Does](#what-the-code-does) + * [Key Features](#key-features) + * [WiFi Management](#wifi-management) + * [Button Handling](#button-handling) + * [Default Button Actions](#default-button-actions) +5. [Tips and tricks](#tips-and-tricks) + +--- + +## Bill of Materials + +| **Component** | **Quantity** | **Description** | **Notes** | +|---------------------------|--------------|-------------------------------------------|---------------------------------------------| +| ESP8266 D1 Mini | 1 | Microcontroller module | | +| SSD1306 OLED Display | 1 | 128x64 resolution, I2C interface | | +| 14250 Rechargeable Battery| 1 | Lithium-ion battery | Make sure you get the rechargeable type, most 14250 are not | +| TP4056 Module | 1 | Charging and protection circuit | Does not need to have a USB connector | +| 6x6 Push Buttons | 3 or 4 | Tactile push buttons | | +| 20mm Piezo Buzzer | 1 | Caseless buzzer for audio | | +| Resistors (10kΩ) | 3 or 4 | Pull-down resistors for buttons | | +| Resistors (220kΩ and 56kΩ)| 1 | Voltage divider | For monitoring the battery charge level | +| Wires | Several | Thin wires for connections | I used wires from inside an old ethernet cable | +| Enclosure | 1 | 3D-printed case | 3D printable STL files are in `hardware/case/` | +| 2x6mm screw | 8 | Small screws for assembling the case | Does not have to be exactly 6mm long | +| 2x2mm screw | 4 | Small screws for the front | Mostly for cosmetic purposes | + +![layout](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/layout.jpg) + +--- + +## Assembly Instructions +--- +### Body + +Push the ESP8266 microcontroller in the ledge on the bottom [the cube body](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/case/SmartCube_Body_3_button.stl), it should 'click in' with the USB-C port facing the hole. + +Body with 3 or 4 button slots is available in the `hardware/case/` + +![Step3](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build3.jpg) + +![Step1](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build1.jpg) + +![Step2](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build2.jpg) + +--- + +### Buttons + +At this step, glue the buttons into the top slots and solder resistors to their outputs. You can connect the resistor outputs together, and don't forget to attach an extra wire to the button inputs, this will later be used to connect them to the 3.3V line. + +![Step4](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build4.jpg) + +Next, solder all of the button outputs to the microcontroller. + +Pin numbers for the buttons (and other components) are defined in the [example config](https://git.kopic.hr/tomislav/SmartCubeV1/src/branch/main/src/example_config.h), and the schematic for the [D1 Mini is here](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/schematics/esp8266.png). +You don't have to follow my exact pin definitions, but I've found this setup to be the easiest way to assemble and fit everything in. The 3-button variant is the standard. If you decide to go with 4 buttons, you'll need to define the extra pin yourself in the code. + +* Button Left (PIN_BTN_L): (D6) GPIO12 +* Button Middle (PIN_BTN_M): (D7) GPIO13 +* Button Right (PIN_BTN_R): (D8) GPIO15 + +Finally, solder the GND wire to the resistor outputs and connect 3.3V to the button inputs. + +![Step5](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build5.jpg) + +--- +### OLED Display + +Screw in the 2x2mm screws and hot glue the SSD1306 to the [front part of the cube](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/case/SmartCube_Front.stl) solder the 4 wires to the OLED display, make sure you have some extra length, 4-5cm should be more than enough + +![Step6](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build6.jpg) + +![Step7](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build7.jpg) + +The OLED display must be connected via I2C on pins: +- **SDA**: D2 (GPIO4) +- **SCL**: D1 (GPIO5) +- **GND**: GND +- **VCC**: 3.3V pin or directly to the TP4056 output + +![Step8](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build8.jpg) + +--- +### Buzzer + +Glue in the buzzer to the [back part of the cube](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/case/SmartCube_Back_Speaker_Side_Hole.stl) with superglue + +As defined in the [example config](https://git.kopic.hr/tomislav/SmartCubeV1/src/branch/main/src/example_config.h) connect: + - the positive wire of the buzzer to the 3.3V + - the negative wire to PIN_BUZZER (D3) GPIO0 + +![Step9](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build9.jpg) +--- + +### Battery Setup + +The battery is optional. Your SmartCube will work fine when powered via USB; however, adding one makes it portable (and much cuter). + +A single 700 mAh 14250 battery lasts about 24 hours. Keep in mind there's currently no way to manually power the Cube off, it will continue running until the battery is depleted. The TP4056 prevents the cell from being completely drained and should protect it from damage. + +* Solder the 14250 battery to the **TP4056 input pins**. +* Wire the **TP4056 output** to the **3.3V pin** on the D1 Mini to power the device. +* Connect the **5V output pin** from the D1 Mini to the **TP4056 input port** to allow charging through the USB data port on the ESP8266. +* *(Optional)* Add a **voltage divider** to monitor battery level on the ESP8266 **A0 pin**: + * **R1 = 220kΩ** (between battery positive and A0) + * **R2 = 56kΩ** (between A0 and GND) + + This scales the battery voltage safely down for measurement (~0-0.85V). + +![batt1](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/batt1.jpg) + +![batt2](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/batt2.jpg) + +![batt3](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/batt3.jpg) + +--- +## Schematics + +This is the basic drawing of the circuit without the battery +![Basic](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/schematics/schematic1.png) + +This is the complete circuit including the battery and a voltage divider +![WithBattery](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/schematics/schematic3.png) + +--- ## Demo Code Explanation This repository contains a basic "Hello, World!" project for the SmartCube. @@ -44,19 +182,18 @@ This demo handles basic system functionality, including: ### Key Features -1. **WiFi Management**: +#### WiFi Management - The [cubeWifiManager](https://git.kopic.hr/tomislav/SmartCubeV1/src/branch/main/src/SmartCube/cubeWifiManager.h) class manages WiFi connectivity seamlessly. - If no known WiFi network is available, it starts a configuration portal and creates an access point (AP), allowing users to connect the SmartCube to a network from another WiFi-enabled device. - The OLED display shows the access point details, such as the AP name and IP address, making the setup process very easy. -2. **Button Handling**: +#### Button Handling - Buttons are mapped to specific GPIO pins: `PIN_BTN_L` (Left), `PIN_BTN_M` (Middle), and `PIN_BTN_R` (Right). - The [cubeButtonHandler](https://git.kopic.hr/tomislav/SmartCubeV1/src/branch/main/src/SmartCube/cubeButtons.h) function, executed in the [loop()](https://git.kopic.hr/tomislav/SmartCubeV1/src/commit/1cb51f502d92a91c6a83ce6364b434db31bfd864/src/main.cpp#L47), monitors and interprets button presses, differentiating between short and long presses. -#### Default Button Actions +##### Default Button Actions - **Right Button**: - - *Short Press*: Turns the OLED display **on** (if previously off). - - *Long Press*: Turns the OLED display **off**, helping conserve power. + - *Long Press*: Turns the OLED display **on** (if previously off). - **Left + Middle Buttons (Simultaneous Long Press)**: - Triggers an ESP8266 reboot, effectively restarting the device. @@ -64,116 +201,7 @@ This demo handles basic system functionality, including: This is meant to provide a minimal starting point for further development with the SmartCube. --- - -## Bill of Materials - -| **Component** | **Quantity** | **Description** | **Notes** | -|---------------------------|--------------|-------------------------------------------|---------------------------------------------| -| ESP8266 D1 Mini | 1 | Microcontroller module | | -| SSD1306 OLED Display | 1 | 128x64 resolution, I2C interface | | -| 14250 Rechargeable Battery| 1 | Lithium-ion battery | Make sure you get the rechargeable type, most 14250 are not | -| TP4056 Module | 1 | Charging and protection circuit | Does not need to have a USB connector | -| 6x6 Push Buttons | 3 or 4 | Tactile push buttons | | -| 20mm Piezo Buzzer | 1 | Caseless buzzer for audio | | -| Resistors (10kΩ) | 3 or 4 | Pull-down resistors for buttons | | -| Resistors (220kΩ and 56kΩ)| 1 | Voltage divider | For monitoring the battery charge level | -| Wires | Several | Thin wires for connections | I used wires from inside an old ethernet cable | -| Enclosure | 1 | 3D-printed case | 3D printable STL files are in `hardware/case/` | -| 2x6mm screw | 8 | Small screws for assembling the case | Does not have to be exactly 6mm long | -| 2x2mm screw | 4 | Small screws for the front | Mostly for cosmetic purposes | - -![layout](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/layout.jpg) - ---- - -## Assembly Instructions ---- -1. **Body** - -Push the ESP8266 microcontroller in the ledge on the bottom [the cube body](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/case/SmartCube_Body_3_button.stl), it should 'click in' with the USB-C port facing the hole. - -Body with 3 or 4 button slots is available in the `hardware/case/` - -![Step3](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build3.jpg) - -![Step1](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build1.jpg) - -![Step2](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build2.jpg) - ---- - -2. **Buttons** - -At this step, glue the buttons into the top slots and solder resistors to their outputs. You can connect the resistor outputs together, and don't forget to attach an extra wire to the button inputs, this will later be used to connect them to the 3.3V line. - -![Step4](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build4.jpg) - -Next, solder all of the button outputs to the microcontroller. - -Pin numbers for the buttons (and other components) are defined in the [example config](https://git.kopic.hr/tomislav/SmartCubeV1/src/branch/main/src/example_config.h), and the schematic for the [D1 Mini is here](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/schematics/esp8266.png). -You don't have to follow my exact pin definitions, but I've found this setup to be the easiest way to assemble and fit everything in. The 3-button variant is the standard. If you decide to go with 4 buttons, you'll need to define the extra pin yourself in the code. - -* Button Left (PIN_BTN_L): (D6) GPIO12 -* Button Middle (PIN_BTN_M): (D7) GPIO13 -* Button Right (PIN_BTN_R): (D8) GPIO15 - -Finally, solder the GND wire to the resistor outputs and connect 3.3V to the button inputs. - -![Step5](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build5.jpg) - ---- -3. **OLED Display** - -Screw in the 2x2mm screws and hot glue the SSD1306 to the [front part of the cube](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/case/SmartCube_Front.stl) solder the 4 wires to the OLED display, make sure you have some extra length, 4-5cm should be more than enough - -![Step6](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build6.jpg) - -![Step7](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build7.jpg) - -The OLED display must be connected via I2C on pins: -- **SDA**: D2 (GPIO4) -- **SCL**: D1 (GPIO5) -- **GND**: GND -- **VCC**: 3.3V pin or directly to the TP4056 output - -![Step8](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build8.jpg) - ---- -4. **Buzzer** - -Glue in the buzzer to the [back part of the cube](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/case/SmartCube_Back_Speaker_Side_Hole.stl) with superglue - -As defined in the [example config](https://git.kopic.hr/tomislav/SmartCubeV1/src/branch/main/src/example_config.h) connect: - - the positive wire of the buzzer to the 3.3V - - the negative wire to PIN_BUZZER (D3) GPIO0 - -![Step9](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/build9.jpg) ---- - -**Battery Setup** - -The battery is optional. Your SmartCube will work fine when powered via USB; however, adding one makes it portable (and much cuter). - -A single 700 mAh 14250 battery lasts about 24 hours. Keep in mind there's currently no way to manually power the Cube off, it will continue running until the battery is depleted. The TP4056 prevents the cell from being completely drained and should protect it from damage. - -* Solder the 14250 battery to the **TP4056 input pins**. -* Wire the **TP4056 output** to the **3.3V pin** on the D1 Mini to power the device. -* Connect the **5V output pin** from the D1 Mini to the **TP4056 input port** to allow charging through the USB data port on the ESP8266. -* *(Optional)* Add a **voltage divider** to monitor battery level on the ESP8266 **A0 pin**: - * **R1 = 220kΩ** (between battery positive and A0) - * **R2 = 56kΩ** (between A0 and GND) - - This scales the battery voltage safely down for measurement (~0-0.85V). - -![batt1](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/batt1.jpg) - -![batt2](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/batt2.jpg) - -![batt3](https://git.kopic.hr/tomislav/SmartCubeV1/raw/branch/main/hardware/pictures/batt3.jpg) - ---- - -## Notes +## Tips and tricks - This is still a work in progress - Everything is pretty tightly packed in there and it's a mess. But it's not as hard to make as it looks.