RomanAlexandroff · RomanAlexandroff · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/Makefile b/Makefile
@@ -19,15 +19,16 @@ ifeq ($(firstword $(MAKECMDGOALS)),format)
   endif
 endif
 
-.PHONY: help release publish-manifest format
+.PHONY: help release publish-manifest format docs
 
 help:
 	@printf '%s\n' \
 		'Available targets:' \
 		'  make release           Run the Firmware Release Manager.' \
 		'  make publish-manifest  Update ota/manifest.json from release-info.json.' \
 		'  make format all        Format all .ino/.c/.cpp/.h files under src/.' \
-		'  make format <file>     Format one file under src/ (basename or src/<file>).'
+		'  make format <file>     Format one file under src/ (basename or src/<file>).' \
+		'  make docs              Build the technical documentation PDF.'
 
 release:
 	@$(MAKE) -C "$(FRM_DIR)" ROOT_DIR="$(CURDIR)" release
@@ -62,3 +63,10 @@ format:
 	fi; \
 	printf '[format] Formatting %s file(s) with clang-format\n' "$${#files[@]}"; \
 	clang-format -i -style=file -- "$${files[@]}"
+
+docs:
+	@set -euo pipefail; \
+	command -v asciidoctor-pdf >/dev/null || { echo 'ERROR: asciidoctor-pdf is required.'; echo 'Install with: gem install asciidoctor-pdf'; exit 1; }; \
+	mkdir -p build; \
+	asciidoctor-pdf docs/tech_documentation/book.adoc -o build/Technical_Documentation.pdf; \
+	echo "[docs] Wrote build/Technical_Documentation.pdf"
diff --git a/README.md b/README.md
@@ -1,12 +1,14 @@
 ![Repository Banner](docs/graphic_materials/github_repo_animation.gif)
 # 42 Smart Cluster Sign
+
+
 ## Table of Contents
 
 - [Introduction](#introduction)
 - [Usage](#usage)
 - [Features](#features)
 - [Components](#components)
-- [The Team behind the Sign](#the-team-behind-the-sign)
+- [Team behind the Sign](#team-behind-the-sign)
 - [Regards](#regards)
 - [Contributing to the Project](#contributing-to-the-project)
 - [License](#license)
@@ -17,7 +19,7 @@
 
 Welcome to the README for the 42 Smart Cluster Sign — a self-sufficient information display designed to be installed on a cluster door. Its purpose is to notify students when the cluster is reserved for an exam and prevent them from accidental entering. The device automatically retrieves exam dates from Intra and displays appropriate warnings and information on its e-paper screen. In the spare time it simply displays the cluster number.
 
-For more information, please, refer to the technical documentation in the docs folder of this repository.
+For more information, such as maintenance and development, device build guide, architecture and function reference, please refer to the [Technical Documentation](docs/tech_documentation/README.md).
 
 
 ## Usage
@@ -54,19 +56,10 @@ The following components are used in the 42 Smart Cluster Sign:
 5. **IKEA RÖDALM photo frame, black, 13x18 cm**: made a good enclosure.
 6. **Custom 3D-printed board**: to hold all the electronics in place.
 
-For more information, please, refer to the bill of materials in the docs folder of this repository.
-
-
-## Contributing to the Project
-
-Contributions to the 42 Smart Cluster Sign project are very welcome! Contact the repository admin [HERE](https://www.linkedin.com/in/roman-alexandrov-a75b89195/) to be added as a Collaborator*. The best place to start would be the [**Issues**](https://github.com/RomanAlexandroff/42-Smart-Cluster-Sign/issues) tab of this repository. It most likely already contains a list of features we'd appreciate your help with and you can start working on them right away. If you have your own ideas, bug fixes, or improvements, feel free to open an issue or submit a pull request.
-
-When contributing, please adhere to the existing code style and follow the established guidelines. Clearly describe your changes and provide any necessary documentation or tests.
-
-*Since the device is intended for use within the 42 network of schools, its development requires personal access to the internal information system. For this reason, only a student or a member of the Bocal staff at a 42 school can become a Collaborator on this project.
+For more information, please, refer to the [Bill of Materials](docs/Bill_of_Materials.xlsx) in the docs folder of this repository (Excel file, not viewable on GitHub -- download to view).
 
 
-## The Team behind the Sign
+## Team behind the Sign
 
 This project is a group effort of various 42 students with support from the 42 Prague Bocal team. Here they are:
 - **roaleksa**, 42 Roma, [linkedin](https://www.linkedin.com/in/roman-alexandrov-a75b89195/) — software and electronic hardware developer. Made the idea reality,
@@ -80,11 +73,19 @@ This project is a group effort of various 42 students with support from the 42 P
 
 ## Regards
 
-The project is based on Jean-Marc Zingg's [GxEPD2](https://github.com/ZinggJM/GxEPD2) library for e-paper displays.
-The project uses the [ArduinoOTA](https://github.com/jandrassy/ArduinoOTA) library by Juraj Andrassy for the Over-The-Air software update functionality.
+The project uses Jean-Marc Zingg's [GxEPD2](https://github.com/ZinggJM/GxEPD2) advanced library of drivers for e-paper displays.
 The Sign's Telegram Bot functionality is provided by Brian Lough's [UniversalTelegramBot](https://github.com/witnessmenow/Universal-Arduino-Telegram-Bot) library.
 
 
+## Contributing to the Project
+
+Contributions to the 42 Smart Cluster Sign project are very welcome! Contact the repository admin [HERE](https://www.linkedin.com/in/roman-alexandrov-a75b89195/) to be added as a Collaborator*. The best place to start would be the [**Issues**](https://github.com/RomanAlexandroff/42-Smart-Cluster-Sign/issues) tab of this repository. It most likely already contains a list of features we'd appreciate your help with and you can start working on them right away. If you have your own ideas, bug fixes, or improvements, feel free to open an issue or submit a pull request.
+
+When contributing, please adhere to the existing code style and follow the established guidelines. Clearly describe your changes and provide any necessary documentation or tests.
+
+*Since the device is intended for use within the 42 network of schools, its development requires personal access to the internal information system. For this reason, only a student or a member of the Bocal staff at a 42 school can become a Collaborator on this project.
+
+
 ## License
 
 The 42 Smart Cluster Sign project is licensed. Please, familiarise yourself with the license before using the software or working on it. The text of the license can be found in this repository.
@@ -94,4 +95,4 @@ Please note that while the project strives to provide accurate information, it i
 
 ## Conclusion
 
-Thank you for your interest in the 42 Smart Cluster Sign project! We hope this README provides you with the necessary information to understand the project's purpose, features, installation process, usage, and maintenance. If you did not find the information you need, please, refer to the technical documentation in this repository. If you have any further questions or need assistance, please don't hesitate to reach out. Happy coding!
+Thank you for your interest in the 42 Smart Cluster Sign project! We hope this README provides you with the necessary information to understand the project's purpose, features, installation process, usage and maintenance. If you did not find the information you need, please refer to the [Technical Documentation](docs/tech_documentation/README.md). If you have any further questions or need assistance, please don't hesitate to reach out to the author on [LinkedIn](https://www.linkedin.com/in/roman-alexandrov-a75b89195/). Happy coding!
diff --git a/docs/Technical Documentation.docx b/docs/Technical Documentation.docx
diff --git a/docs/tech_documentation/01-vocabulary-of-terms.adoc b/docs/tech_documentation/01-vocabulary-of-terms.adoc
@@ -0,0 +1,32 @@
+= Vocabulary of Terms
+:imagesdir: media
+ifndef::backend-pdf[]
+:toc: auto
+:sectnums:
+endif::[]
+
+*42 Smart Cluster Sign* — in the project files may be refered to as „the Sign“, „the device“.
+
+*Campus* — physical premises of a 42 school, mainly consist of clusters.
+
+*Cluster* — an auditorium, a study room, usually full of workspaces with computers. For example, C3 is short for Cluster 3.
+
+*Intra* — a website of the 42 school internal information system, but in this project „Intra“ rather means the school‘s internal information system server, as the Sign never accesses the website as a common user, but only the server via its API.
+
+*Secret* — a credential. Along with a UID, it allows to log into Intra via its API. Usually, good for a month, then it expires. Not to be confused with „a security token“ or just „a token“.
+
+*Security token* — also refered to as „token“, is a unique short-lifespan key given by Intra that allows the device to access data stored on the server. Usually, good for a few hours.
+
+*Seeed Studio XIAO ESP32-C3* — a development board with an ESP32-C3 microcontroller and a battery charging IC under the shield. Has two buttons: „B“ stands for „BOOT“, and „R“ stands for „RESET/REBOOT“. Has a red LED indicating the states of the battery charging process.
+
+*ESP32-C3* — the microcontroller onboard the Seeed Studio XIAO ESP32-C3 development board, located under the shield.
+
+*Deep Sleep* — a functionality of an ESP32-C3 microcontroller allowing it to stay ON while consuming almost no power. The most effective way to save battery charge, but reboots the microcontroller causing all the temporary data in RAM to be lost.
+
+*RTC memory* — a small section of the ESP32-C3 memory that stays powered over Deep Sleep. Data put into this section will survive Deep Sleep, but will not survive resetting the device with the reset button. In this project, only data put into the file system can survive both Deep Sleep and resetting the device with the reset button.
+
+*Light Sleep* — a functionality of an ESP32-C3 microcontroller similar to Deep Sleep. Light Sleep is far less effective in saving battery charge, but does not lose RAM data and allowes to contunue executing the program after sleep.
+
+*OTA* — stands for „Over-The-Air“, functionality that allows updating the software of the microcontroller wirelessly.
+
+*SPIFFS* — stands for Serial Peripheral Interface Flash File System, is one of the ESP32-C3 microcontroller memory partitions dedicated to storing files. In this project (and often on the Internet) the term is used as a synonym to „a file system“. The term also serves as a name to the formerely widly-spread SPIFFS library. Instead of it, this project employs the LittleFS library as more modern and light-weight.
diff --git a/docs/tech_documentation/02-about-the-project.adoc b/docs/tech_documentation/02-about-the-project.adoc
@@ -0,0 +1,8 @@
+= About the Project
+:imagesdir: media
+ifndef::backend-pdf[]
+:toc: auto
+:sectnums:
+endif::[]
+
+This project is designed to manage and display information on a smart sign for a 42 campus cluster. The sign displays various messages and images, including exam schedules, battery status, and OTA updates. It communicates with the 42 Intra API and a Telegram bot to fetch and display relevant information.
diff --git a/docs/tech_documentation/03-contractors-requirements.adoc b/docs/tech_documentation/03-contractors-requirements.adoc
@@ -0,0 +1,40 @@
+= Contractor's Requirements and How the Sign Matches Them
+:imagesdir: media
+ifndef::backend-pdf[]
+:toc: auto
+:sectnums:
+endif::[]
+
+The finished device must fulfill the following requirements:
+
+. *Auditorium status display*: the device must always display the current status of the auditorium, indicating whether it is free or if an exam is in progress.
++
+The Sign displays the number of the auditorium in calm black and white colours to indicate that the room is available for everyone or it displays the „exam in progress“ sign in bright red and black colours to show that the room shall not be entered by those who do not participate in the exam. The Sign is never blank.
+
+. *Advance notification*: the device should notify students in advance on exam days about the need to vacate the auditorium.
++
+The Sign displays a note with the exact time of the upcoming exam right from the morning of that day. 1 hour before the exam, the black-white-and-red „reserve for exam“ sign with time left starts being displayed.
+
+. *Autonomy*: the device must operate independently, performing its tasks and solving problems that arise without requiring the time or intervention of the educational institution's staff.
++
+The Sign can connect to the Internet, access the institution server API and pull exams date and time. This is how it knows when to display the apropriate state of the auditorium. The Sign software is designed with all the common negative situations in mind which ensures the Sign does not bother anyone unless it absolutely needs to.
+
+. *Problem reporting*: the device must be capable of reporting issues that cannot be resolved without assistance from the educational institution's staff.
++
+When the Sign fails to resolve an unordinary situation itself and requires assistance, it displays an apropriate error message on its display as well as sends a detailed error report to its Telegram chat.
+
+. *Support and expandability*: the device should be designed for support and expansion, allowing any student of the educational institution to contribute to the project, develop new functionality, and upload new software onto the device.
++
+The Sign project was chosen to be made using Arduino IDE as the most beginners-friendly developing platform. The software was developed using a straightforward bare-metal approach to maintain easy-to-follow program logic. The Sign has a standart USB-C port for flashing its software, monitoring its Serial port and charging its battery. The microcontroller used in the project has inner USB controller which eliminates the need of using a UART-TTL adapter. The microcontroller pins are equipped with standart Dupont sockets which allows anyone to change used pins and add new hardware by simply connecting it to the microcontroller with Dupont cables. The Sign is securelly fixed on the wall with 4 furniture double ball catches, which at the same time allow to take the Sign off the wall for maintanance.
+
+. *Safety*: the device must ensure safety by incorporating protective elements for potentially dangerous electronic components.
++
+The battery used in the project has an embedded protection against shortcuts, overcharging and ungercharging, which has the ability of completely disconnecting the battery from the rest of the circuit. The battery charging IC is capable of adapting its charging power, applying lower voltages when the battery is low on charge or close to being fully charged. The charging IC generally uses slightly lower charging rate than the standart charging rate for this particular battery, which will result in the battery longer life.
+
+. *Rechargeable operation*: the device must operate on a rechargeable battery, include a common charging connector, and provide indications for the charging process and its completion.
++
+The Sign employs an internal high-capacity rechargeable battery, which insures a long lasting operation without the need of changing batteries. The battery can be recharged by plugging the Sign into any 5V power adapter. The Sign has a USB-C connector for recharging the battery as well as for flashing the software. The Sign employs a red LED to indicate an ongoing charging process.
+
+. *Design compatibility*: both the graphical user interface (GUI) and the physical appearance of the device must align with the established style of the educational institution's interior design.
++
+The body of the Sign is made of black wooden frame with mate finish, which perfectly matches the mate-black profile of the auditorium glass door. The GUI was designed inspired by the painings on the walls of the institution as well as the „42“ logo, thus nicely matching the overal style of the interiors.
diff --git a/docs/tech_documentation/04-program-run-overview.adoc b/docs/tech_documentation/04-program-run-overview.adoc
@@ -0,0 +1,21 @@
+= General Description of the Program Run
+:imagesdir: media
+ifndef::backend-pdf[]
+:toc: auto
+:sectnums:
+endif::[]
+
+Let's take a look at one day of the 42 Smart Cluster Sign‘s life. Let’s say that on this particular day there is an exam scheduled for 13:00 and it will last for 3 hours.
+
+It is still night and the Sign is showing the cluster number with the default pictograms from the day before, while still being asleep. It is normal for the Sign to sleep all the time. It has its scheduled hours to wake up and check if something needs to be done. They are 6, 9, 12, 15, 18 and 21 o’clock (could have been changed in the program). But it is still too early.
+
+Time passes by. Now, it is 6:00 in the morning. The Sign wakes up to check if there are exams today. It goes online, pulls the information from the Intra server and sees that there will be an exam starting at 13:00 and ending at 16:00. The Sign replaces the default pictograms from yesterday with a note “_The cluster will be reserved for an exam today at 13:00_” while still displaying the cluster number. Since there is nothing more for the Sign to do, it sets its alarm clock for 12:00 - an hour before the exam - and goes back to sleep.
+
+It is 12 o'clock and the Sign wakes up again to get ready for the exam. It checks Intra to make sure the exam was not canceled during its sleep and that there is at least 1 person attending. If everything checks, it replaces the cluster number with a big warning sign that says: “_RESERVATION! The cluster is reserved for an exam. Please, vacate it in due time. You have XX minutes left_”. Instead of XX it first says 50 minutes, then 25 minutes and finally 5 minutes left.
+
+Finally, it is 13:00. The exam begins. The Sign changes the previous warning sign for a new one, saying “_DO NOT ENTER! Exam in progress!_”. At this point the Sign has nothing else to do, so again it sets its alarm clock for 16:00 - the end of the exam - and goes to sleep.
+
+At 16 o'clock the Sign wakes up, checks Intra, finds no more exams for today, replaces the warning sign with a cluster number with the default pictograms, sets its alarm clock until the next scheduled wake up - in this case 18:00 - and goes back to sleep.
+
+At 18 o'clock the Sign wakes up, checks Intra and finds no more exams, so it does nothing. Later, at 21 o’clock it wakes up for the last time today, finding nothing more to be done. Its work for today is over. It goes to sleep to wake up again the next morning at 6.
+