refactor: rename site/ to explorer/

.github/workflows/pages.yml

@@ -5,13 +5,13 @@ on:
     branches: [master]
     paths:
       - README.md
-      - "site/**"
+      - "explorer/**"
       - .github/workflows/pages.yml
       - .github/scripts/next-version.sh
   pull_request:
     paths:
       - README.md
-      - "site/**"
+      - "explorer/**"
       - .github/workflows/pages.yml
       - .github/scripts/next-version.sh
   workflow_dispatch:
@@ -48,16 +48,16 @@ jobs:
           node-version: 22
 
       - name: Test the README parser and map layout
-        run: node --test site/parser.test.mjs
+        run: node --test explorer/parser.test.mjs
 
       - name: Warn about README sections that are not on the map
-        run: node site/tools/coverage.mjs
+        run: node explorer/tools/coverage.mjs
 
       - name: Assemble the site
         run: |
           mkdir _site
-          cp site/*.html site/*.css site/*.js site/map.json README.md _site/
-          cp -r site/fonts site/assets _site/
+          cp explorer/*.html explorer/*.css explorer/*.js explorer/map.json README.md _site/
+          cp -r explorer/fonts explorer/assets _site/
 
       - name: Install Chromium
         run: |
@@ -68,7 +68,7 @@ jobs:
         id: fingerprint
         # Rendered before build.json exists, so the revision line is not part of the fingerprint.
         run: |
-          node site/tools/render.mjs _site / fingerprint
+          node explorer/tools/render.mjs _site / fingerprint
           echo "sha256=$(sha256sum fingerprint/Embedded-Engineering-Roadmap.png | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
 
       - name: Decide the version
@@ -87,7 +87,7 @@ jobs:
         run: |
           node -e 'console.log(JSON.stringify({ version: process.env.VERSION, date: process.env.DATE }))' > _site/build.json
           cat _site/build.json
-          node site/tools/render.mjs _site / _site
+          node explorer/tools/render.mjs _site / _site
 
       - uses: actions/upload-artifact@v4
         with:

CONTRIBUTING.md

@@ -30,7 +30,7 @@ Contributions from everyone are welcomed. To keep the roadmap practical, accessi
 - Contributions should match the topics and structure of the roadmap.
 - Areas where contributors have experience or genuine interest should be focused on.
 - If a new topic is thought to make the roadmap more complete, it may be suggested. New topics should be proposed thoughtfully, considering their usefulness and relevance for other learners.
-- Connections between topics on the map are listed in `site/map.json` under `links` as `["Topic", "Other topic", "why they are related"]`, using the names shown on the map. Connect topics that a learner should study together or that depend on each other, and keep the reason to one short sentence. Tests fail if a name is misspelled, a pair is listed twice or a topic has no connection.
+- Connections between topics on the map are listed in `explorer/map.json` under `links` as `["Topic", "Other topic", "why they are related"]`, using the names shown on the map. Connect topics that a learner should study together or that depend on each other, and keep the reason to one short sentence. Tests fail if a name is misspelled, a pair is listed twice or a topic has no connection.
 
 ## 6. How the README Feeds the Interactive Roadmap
 
@@ -38,8 +38,8 @@ The [interactive roadmap](https://m3y54m.github.io/Embedded-Engineering-Roadmap/
 
 - **Topics** come from heading depth: `##` is a group, `###` a main topic, `####` and deeper are subtopics. The emojis in headings (✳️ 🔵 🔶 🔸) are decoration only. Renaming a heading changes its link (`#/topic-name`).
 - **Resources** are list items in the form `- [📘👶💎 Title](https://url)`, optionally followed by a dash and a short note. Symbols: 📘 book, 🎞️ video, 📝 article, 🔗 link, 🎧 audio, 👶 beginner, 💎 essential. `python3 .github/scripts/check_readme.py` checks the format and duplicates.
-- **The map** (`site/map.json`) draws only the main topics. Each label on it opens the README heading with the same name. If the wording differs, or the label has no section of its own, add `"Label": ["README heading"]` to `readme` in `site/map.json`. A new main topic needs a README section and a box in `site/map.json` (and at least one entry in `links`), unless it should stay off the map: then list its title or group in `offMap`. CI warns about main topics that are neither.
-- **Preview and test locally:** `python3 -m http.server 8765` from the repository root, then open `/site/`; `node --test site/parser.test.mjs` runs the checks CI runs.
+- **The map** (`explorer/map.json`) draws only the main topics. Each label on it opens the README heading with the same name. If the wording differs, or the label has no section of its own, add `"Label": ["README heading"]` to `readme` in `explorer/map.json`. A new main topic needs a README section and a box in `explorer/map.json` (and at least one entry in `links`), unless it should stay off the map: then list its title or group in `offMap`. CI warns about main topics that are neither.
+- **Preview and test locally:** `python3 -m http.server 8765` from the repository root, then open `/explorer/`; `node --test explorer/parser.test.mjs` runs the checks CI runs.
 
 ## 7. Versioning and Releases
 

README.md

@@ -125,7 +125,7 @@ If you have reservations about relying on AI advice alone, you can also ask your
 - [🔗 Electrical Engineering Stack Exchange](https://electronics.stackexchange.com/)
 - [🔗 Reddit · r/embedded](https://www.reddit.com/r/embedded/)
 
-### ✳️ Career Development
+### 💼 Career Development
 
 As an embedded systems engineer, it's essential to stay up-to-date with industry trends, best practices, and new technologies to advance your career. Here are some resources to help you achieve your career goals:
 
@@ -414,13 +414,19 @@ _________________
 
 Mastering programming fundamentals and software development principles is essential for a successful embedded design. Embedded systems demand efficient code, optimized data management, reusable design patterns, and effective memory management to function effectively in resource-constrained environments. Embedded developers must possess a strong foundation in these core concepts to create reliable and performant embedded systems.
 
-#### 🔵 Basic Discrete Mathematics
+#### 🔵 Discrete Mathematics
+
+Discrete mathematics is the theoretical basis of computer science and engineering. The parts most useful to embedded engineers are logic and switching algebra (digital circuit design), automata theory (state machines and protocols), combinatorics, coding theory (data transmission and audio/video codecs) and modular arithmetic (checksums and cryptography).
 
 - [🎞️ Coursera - Introduction to Discrete Mathematics for Computer Science Specialization](https://www.coursera.org/specializations/discrete-mathematics)
 - [📘👶 Open Access Discrete Mathematics Books by LibreTexts](https://math.libretexts.org/Bookshelves/Combinatorics_and_Discrete_Mathematics)
 - [📘👶 Essential Discrete Mathematics for Computer Science - Harry Lewis, Rachel Zax](https://dl.acm.org/doi/book/10.5555/3388468)
 - [📘👶 Guide to Discrete Mathematics - Gerard O'Regan, Springer](https://link.springer.com/book/10.1007/978-3-030-81588-2)
 - [📘💎 Bridge to Abstract Mathematics, AMS](https://bookstore.ams.org/view?ProductCode=TEXT/22)
+- [📘💎 Discrete Mathematics and its applications by Rosen](https://dl.acm.org/doi/book/10.5555/579402)
+- [📘💎 Discrete Mathematics with Applications by Susanna S. Epp](https://dl.acm.org/doi/book/10.5555/1941983)
+- [📘💎 Switching and Finite Automata Theory, Cambridge Press](https://dl.acm.org/doi/10.5555/1708070)
+- [📘💎 The Mathematics of Cellular Automata by Jane Hawkins, AMS](https://bookstore.ams.org/stml-108)
 
 #### 🔵 Algorithms & Data Structures
 
@@ -1190,8 +1196,6 @@ Embedded Linux is a specialized version of the Linux operating system tailored f
 - [🔗 Linux From Scratch - step-by-step instructions for building your own custom Linux system](https://www.linuxfromscratch.org/)
 - [🔗 Automotive Grade Linux (AGL)](https://docs.automotivelinux.org/)
 - [🔗 Real Time Linux and `PREEMPT_RT` Patch](https://wiki.linuxfoundation.org/realtime/start)
-- [🔗 Android Open Source Project](https://source.android.com)
-- [🔗 Android Automotive](https://source.android.com/docs/automotive)
 
 ##### 🔶 Linux Kernel
 
@@ -1230,6 +1234,20 @@ Embedded Linux is a specialized version of the Linux operating system tailored f
 - [📘 Bootlin Embedded Linux, Kernel, drivers, Yocto, Buildroot and Graphics Training](https://bootlin.com/training/)
 - [🔗 meta-raspberrypi - Yocto/OpenEmbedded layer for Raspberry Pi boards](https://meta-raspberrypi.readthedocs.io/en/latest/)
 
+##### 🔶 Embedded Android
+
+Embedded Android builds on Embedded Linux: the device runs a Linux kernel with Android-specific additions, and the Android Open Source Project (AOSP) adds its own build system, hardware abstraction layers (HALs) and framework on top. Learn Embedded Linux first, then how AOSP is built, ported to a board and extended with HALs and native (NDK) code.
+
+- [🔗💎 Android Open Source Project](https://source.android.com)
+- [🔗👶 AOSP Architecture Overview](https://source.android.com/docs/core/architecture)
+- [🔗 Try Android Development - Download, Build and Flash AOSP](https://source.android.com/docs/setup/start)
+- [🔗 Android Kernel Overview](https://source.android.com/docs/core/architecture/kernel)
+- [🔗 Hardware Abstraction Layer (HAL) Overview](https://source.android.com/docs/core/architecture/hal)
+- [🔗 Get Started with the Android NDK](https://developer.android.com/ndk/guides)
+- [📘💎 Embedded Android - Karim Yaghmour](https://www.oreilly.com/library/view/embedded-android/9781449327958/)
+- [📘 Android System Development Training (Slides and Labs) - Bootlin](https://bootlin.com/doc/legacy/android/)
+- [🔗 Android Automotive](https://source.android.com/docs/automotive)
+
 #### 🔵 Multithreading & Parallel Processing
 
 - [📝 Threading/Concurrency vs Parallelism](http://www.danielmoth.com/Blog/threadingconcurrency-vs-parallelism.aspx)
@@ -1582,35 +1600,6 @@ AUTOSAR, or AUTomotive Open System ARchitecture, is a global industry standard f
 - [🔗💎 OSEK/VDX Operating System Specification 2.2.3](https://www.osek-vdx.org/mirror/os223.pdf)
 - [🔗💎 OSEK/VDX OIL (OSEK Implementation Language) Specification 2.4.1](https://www.osek-vdx.org/mirror/oil241.pdf)
 
-_________________
-
-### ✳️ Appendix-A: Advanced Topics
-
-#### 🔵 Discrete Mathematics
-
-A common subject that is essential to Computer Science students and some Math/Electrical Engineering Majors based on the [Association For Computing Machinery Guidelines for CS/CE education](https://www.acm.org/education/curricula-recommendations). It houses the most essential subjects for _abstract mathematical modelling_ and _theory of computation_. Furthermore, it helps students to establish the essential engineering mindset that represents the common basis among all computer science and computer engineering domains. However, Logic, Theory of combinatorics, Coding Theory, and Theory of Computation are among the most essential subjects for Embedded Systems Engineers.
-
-_**Goal of learning Discrete Mathematics:**_ Embedded Systems Engineers should be able to grasp most of these information sooner or later based on their subspeciality; as it explains the scientific and theoretical basis of computer engineering (e.g., Coding Theory for Audio/Video Encoding/Decoding and Data Transmission - Automata Theory for event control and data transmission - Logic for digital circuit design and switching algebra - $$\Pi$$ Calculus and Automata Theory for Concurrency Modelling).
-
-_Discrete Mathematics_ is a multi-semester course that involves subjects about the theoretical mathematical basis of computer science, including but not limited to:
-
-- Logic (Propositional, Quantificational and Normal Forms).
-- Axiomatic Set Theory (Sets, Operations on sets, and Power Sets).
-- Relation Sets and Function Theory (i.e., $$\lambda$$ Calculus).
-- Theory of combinatorics.
-- Matrix and Graph Theory.
-- Theory of computation (i.e., Computational Automata Theory, Computational Complexity, and Computational Computability).
-- Automata Theory (e.g., Finite-state Machines, Pushdown Automata, Turing Machines, and Cellular Automata).
-- Process Modelling/Calculi (i.e., $$\pi$$ Calculus).
-- Coding Theory.
-- Division Theorem Modular Arithmetics (Parts of Number Theory).
-- [📘💎 Discrete Mathematics and its applications by Rosen](https://dl.acm.org/doi/book/10.5555/579402)
-- [📘💎 Discrete Mathematics with Applications by Susanna S. Epp](https://dl.acm.org/doi/book/10.5555/1941983)
-- [📘💎 Switching and Finite Automata Theory, Cambridge Press](https://dl.acm.org/doi/10.5555/1708070)
-- [📘💎 Discrete Mathematical Structures by Bernard Kolman](https://www.pearson.com/en-us/subject-catalog/p/discrete-mathematical-structures-classic-version/P200000006227/9780137538782?srsltid=AfmBOooBdohmNtq7Wu42tHwSt7lUma46hBmKjqk8XJ8NNI6sf2-4-1kg)
-- [📘💎 Invitation to Discrete Mathematics, Oxford University Press](https://global.oup.com/academic/product/invitation-to-discrete-mathematics-9780198570431?cc=eg&lang=en&)
-- [📘💎 The Mathematics of Cellular Automata by Jane Hawkins, AMS](https://bookstore.ams.org/stml-108)
-
 ## History
 
 At first this was meant to be my personal reading list but as the list gradually became bigger and bigger, I wondered why not share it with others. So I did research on current job postings for embedded engineering roles, selecting the most frequent skills and including them on a roadmap. In order to make the roadmap more comprehensive I also added some basic skills and finally came up with what you see here.
@@ -1633,4 +1622,4 @@ Special thanks to my friends in the community of Iranian Embedded Engineers in T
 
 If you think that this roadmap can be improved in anyway or you know about some good learning resources that can be added here, please start an issue or a pull request. I’ll be maintaining and updating this repository frequently.
 
-The roadmap image and PDF are generated from this repository. Topics, descriptions and learning resources come from this README; where each topic sits on the map and how important it is come from [`site/map.json`](site/map.json). Edit those files and the interactive explorer in [`site/`](site) renders the PNG and PDF automatically.
+The roadmap image and PDF are generated from this repository. Topics, descriptions and learning resources come from this README; where each topic sits on the map and how important it is come from [`explorer/map.json`](explorer/map.json). Edit those files and the interactive explorer in [`explorer/`](explorer) renders the PNG and PDF automatically.

explorer/map.json

@@ -488,7 +488,7 @@
     "Microcontrollers": ["rtos", "mcu"],
     "Interfaces & Protocols": ["basic", "wireless", "highSpeed", "industrial", "cellular", "network", "automotive", "display"]
   },
-  "offMap": ["Don't Know Where to Start!", "Appendix-A: Advanced Topics"],
+  "offMap": ["Don't Know Where to Start!"],
   "readme": {
     "ADC / DAC": ["ADC", "DAC"],
     "Buildroot / Yocto": ["Buildroot", "Yocto"],

explorer/tools/coverage.mjs

@@ -1,5 +1,5 @@
 // Warns (never fails) about README sections that have no place on the map yet.
-// Usage: node site/tools/coverage.mjs        Sections listed in map.json "offMap" (titles or group names) are skipped.
+// Usage: node explorer/tools/coverage.mjs        Sections listed in map.json "offMap" (titles or group names) are skipped.
 import { readFileSync } from 'node:fs';
 import { parseRoadmap } from '../parser.js';
 import { linkDiagram } from '../diagram.js';
@@ -15,6 +15,6 @@ const skipped = new Set(map.offMap || []);
 const missing = data.root.children.filter((t) => !skipped.has(t.title) && !skipped.has(t.group) && !onMap(t));
 
 for (const t of missing) {
-  console.log(`::warning file=README.md,title=Not on the roadmap map::"${t.title}" has no box on the map. Add it to site/map.json, or to "offMap" if it should stay off the map (see CONTRIBUTING.md).`);
+  console.log(`::warning file=README.md,title=Not on the roadmap map::"${t.title}" has no box on the map. Add it to explorer/map.json, or to "offMap" if it should stay off the map (see CONTRIBUTING.md).`);
 }
 console.log(missing.length ? `${missing.length} README section(s) are not on the map.` : 'Every README section is on the map or listed in "offMap".');

explorer/tools/render.mjs

@@ -1,13 +1,13 @@
 // Renders the roadmap map to an A4 PDF and a PNG with headless Chromium, straight from the site.
-// Usage: node site/tools/render.mjs [rootDir] [pagePath] [outDir]
-//   defaults: repository root, /site/, ./dist        (needs: npm install --no-save playwright)
+// Usage: node explorer/tools/render.mjs [rootDir] [pagePath] [outDir]
+//   defaults: repository root, /explorer/, ./dist        (needs: npm install --no-save playwright)
 import { createServer } from 'node:http';
 import { mkdir, readFile } from 'node:fs/promises';
 import { extname, join, resolve, sep } from 'node:path';
 import { chromium } from 'playwright';
 
 const root = resolve(process.argv[2] || '.');
-const pagePath = process.argv[3] || '/site/';
+const pagePath = process.argv[3] || '/explorer/';
 const outDir = resolve(process.argv[4] || 'dist');
 const NAME = 'Embedded-Engineering-Roadmap';
 const PNG_SCALE = 2;