From db5ae6eb6b9b461a7e9fda2369c8b52a0acffdb9 Mon Sep 17 00:00:00 2001 From: Jarno Date: Tue, 26 May 2026 21:09:10 +0300 Subject: [PATCH] Initialize docs and hello display --- .gitignore | 5 +++ .vscode/extensions.json | 10 +++++ AGENTS.md | 29 ++++++++++++++ README.md | 51 ++++++++++++++++++++++++ docs/hardware-notes.md | 84 ++++++++++++++++++++++++++++++++++++++++ docs/project-overview.md | 68 ++++++++++++++++++++++++++++++++ include/README | 37 ++++++++++++++++++ lib/README | 46 ++++++++++++++++++++++ platformio.ini | 18 +++++++++ src/main.cpp | 18 +++++++++ test/README | 11 ++++++ 11 files changed, 377 insertions(+) create mode 100644 .gitignore create mode 100644 .vscode/extensions.json create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 docs/hardware-notes.md create mode 100644 docs/project-overview.md create mode 100644 include/README create mode 100644 lib/README create mode 100644 platformio.ini create mode 100644 src/main.cpp create mode 100644 test/README diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..89cc49c --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +.pio +.vscode/.browse.c_cpp.db* +.vscode/c_cpp_properties.json +.vscode/launch.json +.vscode/ipch diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..080e70d --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,10 @@ +{ + // See http://go.microsoft.com/fwlink/?LinkId=827846 + // for the documentation about the extensions.json format + "recommendations": [ + "platformio.platformio-ide" + ], + "unwantedRecommendations": [ + "ms-vscode.cpptools-extension-pack" + ] +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..65f2c74 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# Project Rules + +This file defines repository-specific working rules for future development. + +## Workflow Rules + +- Never upload or push firmware to the board. +- The user always performs hardware flashing manually. +- Local compilation is allowed to verify code validity. + +## Architecture Rules + +- Prefer a simple module structure. +- Keep UI/navigation behavior separate from screen content. +- The carousel or screen-switching logic must be agnostic to the specific data shown on each screen. +- Keep external data integrations in their own modules. +- Weather API access should live in a dedicated module rather than inside display or navigation code. +- Keep hardware access, display rendering, navigation logic, and data fetching cleanly separated. + +## Design Intent + +Examples of the intended separation: + +- A display carousel module manages which screen is active. +- Individual screen modules decide how their own content is rendered. +- Sensor modules handle sensor reads and related formatting inputs. +- Network/data modules fetch and prepare remote data such as weather or time. + +The goal is to keep the codebase easy to extend without tightly coupling unrelated responsibilities. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ad4d859 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# Arduino Info Display + +Small info display project for an Arduino MKR1000 with: + +- SH1106 OLED display +- AM2302 temperature and humidity sensor +- Two control buttons + +The device is intended to show a compact set of useful screens, navigated with: + +- `Select` button +- `Next` button + +## Planned Screens + +The display should support at least these views: + +- Local time +- Weather forecast +- Temperature from the AM2302 sensor +- Humidity from the AM2302 sensor + +Additional screens can be added later once the basic navigation and data sources are in place. + +## Project Status + +This repository is currently in the documentation and planning stage. + +- PlatformIO project initialized +- Target board configured as `mkr1000USB` +- Initial hardware wiring notes documented +- Application code not started yet + +## Repository Layout + +- [`platformio.ini`](platformio.ini): PlatformIO configuration +- [`src/main.cpp`](src/main.cpp): Placeholder application entry point +- [`docs/project-overview.md`](docs/project-overview.md): Functional scope and behavior +- [`docs/hardware-notes.md`](docs/hardware-notes.md): Component and wiring notes + +## Initial Goals + +- Build a stable display loop for multiple screens +- Support simple button-based navigation +- Read local temperature and humidity from the AM2302 +- Show time and weather information on the OLED +- Keep the software structure easy to extend later + +## Notes + +The current hardware pin mapping is documented in [`docs/hardware-notes.md`](docs/hardware-notes.md). That file can be extended later with any extra electrical notes, display module specifics, or wiring photos if needed. diff --git a/docs/hardware-notes.md b/docs/hardware-notes.md new file mode 100644 index 0000000..63454fc --- /dev/null +++ b/docs/hardware-notes.md @@ -0,0 +1,84 @@ +# Hardware Notes + +## Core Components + +- Arduino MKR1000 +- SH1106 OLED display +- AM2302 temperature and humidity sensor +- Two momentary buttons for user input + +## Planned Responsibilities + +### Arduino MKR1000 + +- Main controller +- Sensor reading +- Display updates +- Button input handling +- Network connectivity for time and weather data + +### SH1106 OLED Display + +- Render the current screen +- Present concise text-based information + +### AM2302 Sensor + +- Provide ambient temperature +- Provide ambient humidity + +### Buttons + +- `Next` button for navigation +- `Select` button for action or mode selection + +## Wiring Status + +The physical wiring is already assembled. Current documented wiring is: + +## Button Wiring + +### Select button + +- Signal pin: `A5` +- Wiring: pull-up with `10K` resistor + +### Next button + +- Signal pin: `A4` +- Wiring: pull-up with `10K` resistor + +## Sensor Wiring + +### AM2302 + +- Measurement/data pin: `A3` +- `VCC` -> `3V3` +- `GND` -> `GND` + +## Display Wiring + +### SH1106 + +- Interface: `I2C` +- `SCK` -> `SCL` +- `SDA` -> `SDA` +- `VCC` -> `5V` +- `GND` -> `GND` + +## Ground + +All component ground pins are connected to common `GND`. + +## Assumptions To Verify Later + +- The SH1106 module is compatible with the MKR1000 voltage levels +- The AM2302 is powered within its supported operating range +- The button pull-up arrangement matches the intended firmware logic +- Available pins are sufficient for the display, sensor, and both buttons + +## Risks To Keep In Mind + +- OLED modules may vary by interface and initialization details +- Sensor timing can be sensitive depending on the library used +- Network-based features may require retry logic and fallback screen states diff --git a/docs/project-overview.md b/docs/project-overview.md new file mode 100644 index 0000000..cb49ad8 --- /dev/null +++ b/docs/project-overview.md @@ -0,0 +1,68 @@ +# Project Overview + +## Purpose + +This project will create a small standalone information display using an Arduino MKR1000. The device is meant to provide quick access to a few important data views on an SH1106 OLED screen with very simple physical controls. + +## User Interaction + +Two buttons are planned: + +- `Next`: move to the next available screen or option +- `Select`: confirm an option or trigger a context-specific action + +The exact behavior can stay minimal at first. A practical initial version is: + +- `Next` cycles through screens +- `Select` toggles a secondary mode when needed + +## Minimum Feature Scope + +The first usable version should include: + +- Time screen for local time +- Weather forecast screen +- Temperature screen using the AM2302 +- Humidity screen using the AM2302 + +## Suggested Screen Behavior + +To keep the interface simple on a small display: + +- Show one primary screen at a time +- Keep text large and readable +- Refresh local sensor data regularly +- Refresh network-based data less frequently than local sensor data +- Avoid cluttered layouts + +## Data Sources + +### Local data + +- Temperature from AM2302 +- Humidity from AM2302 + +### External data + +- Local time +- Weather forecast + +The exact source and synchronization method for time and weather can be decided later during implementation. + +## Non-Goals For Now + +These are intentionally out of scope for the initial documentation phase: + +- Final UI layout details +- Library selection +- Network/API implementation +- Pin-level firmware implementation +- Power optimization + +## Open Items + +- Document exact wiring for the display, sensor, and buttons +- Decide how local time will be synchronized +- Decide where weather forecast data will come from +- Define how button behavior should work on each screen +- Confirm refresh intervals for sensor and network data diff --git a/include/README b/include/README new file mode 100644 index 0000000..49819c0 --- /dev/null +++ b/include/README @@ -0,0 +1,37 @@ + +This directory is intended for project header files. + +A header file is a file containing C declarations and macro definitions +to be shared between several project source files. You request the use of a +header file in your project source file (C, C++, etc) located in `src` folder +by including it, with the C preprocessing directive `#include'. + +```src/main.c + +#include "header.h" + +int main (void) +{ + ... +} +``` + +Including a header file produces the same results as copying the header file +into each source file that needs it. Such copying would be time-consuming +and error-prone. With a header file, the related declarations appear +in only one place. If they need to be changed, they can be changed in one +place, and programs that include the header file will automatically use the +new version when next recompiled. The header file eliminates the labor of +finding and changing all the copies as well as the risk that a failure to +find one copy will result in inconsistencies within a program. + +In C, the convention is to give header files names that end with `.h'. + +Read more about using header files in official GCC documentation: + +* Include Syntax +* Include Operation +* Once-Only Headers +* Computed Includes + +https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html diff --git a/lib/README b/lib/README new file mode 100644 index 0000000..9379397 --- /dev/null +++ b/lib/README @@ -0,0 +1,46 @@ + +This directory is intended for project specific (private) libraries. +PlatformIO will compile them to static libraries and link into the executable file. + +The source code of each library should be placed in a separate directory +("lib/your_library_name/[Code]"). + +For example, see the structure of the following example libraries `Foo` and `Bar`: + +|--lib +| | +| |--Bar +| | |--docs +| | |--examples +| | |--src +| | |- Bar.c +| | |- Bar.h +| | |- library.json (optional. for custom build options, etc) https://docs.platformio.org/page/librarymanager/config.html +| | +| |--Foo +| | |- Foo.c +| | |- Foo.h +| | +| |- README --> THIS FILE +| +|- platformio.ini +|--src + |- main.c + +Example contents of `src/main.c` using Foo and Bar: +``` +#include +#include + +int main (void) +{ + ... +} + +``` + +The PlatformIO Library Dependency Finder will find automatically dependent +libraries by scanning project source files. + +More information about PlatformIO Library Dependency Finder +- https://docs.platformio.org/page/librarymanager/ldf.html diff --git a/platformio.ini b/platformio.ini new file mode 100644 index 0000000..b39a1cd --- /dev/null +++ b/platformio.ini @@ -0,0 +1,18 @@ +; PlatformIO Project Configuration File +; +; Build options: build flags, source filter +; Upload options: custom upload port, speed and extra flags +; Library options: dependencies, extra library storages +; Advanced options: extra scripting +; +; Please visit documentation for the other options and examples +; https://docs.platformio.org/page/projectconf.html + +[env:mkr1000USB] +platform = atmelsam +board = mkr1000USB +framework = arduino +lib_deps = + arduino-libraries/WiFi101@^0.16.1 + olikraus/U8g2@^2.36.18 + adafruit/DHT sensor library@^1.4.7 diff --git a/src/main.cpp b/src/main.cpp new file mode 100644 index 0000000..8817214 --- /dev/null +++ b/src/main.cpp @@ -0,0 +1,18 @@ +#include +#include +#include + +// SH1106 128x64 OLED over hardware I2C, rotated 180 degrees for flipped mounting. +U8G2_SH1106_128X64_NONAME_F_HW_I2C display(U8G2_R2, U8X8_PIN_NONE); + +void setup() { + display.begin(); + display.clearBuffer(); + display.setFont(u8g2_font_ncenB08_tr); + display.drawStr(18, 32, "Hello, world!"); + display.sendBuffer(); +} + +void loop() { + delay(1000); +} diff --git a/test/README b/test/README new file mode 100644 index 0000000..9b1e87b --- /dev/null +++ b/test/README @@ -0,0 +1,11 @@ + +This directory is intended for PlatformIO Test Runner and project tests. + +Unit Testing is a software testing method by which individual units of +source code, sets of one or more MCU program modules together with associated +control data, usage procedures, and operating procedures, are tested to +determine whether they are fit for use. Unit testing finds problems early +in the development cycle. + +More information about PlatformIO Unit Testing: +- https://docs.platformio.org/en/latest/advanced/unit-testing/index.html