📝 Add ARCHITECTURE.md

- ⬆️ libhal-bootstrap/3.0.0
- Rename hardware_map to resource_list

.github/workflows/1.0.0.yml → .github/workflows/deploy.yml

@@ -1,11 +1,12 @@
-name: 🚀 Release 1.0.0
+name: 🚀 Deploy
 
 on:
   workflow_dispatch:
 
 jobs:
   deploy:
+    if: startsWith(github.ref, 'refs/tags/')
     uses: libhal/ci/.github/workflows/deploy_all.yml@5.x.y
     with:
-      version: 1.0.0
+      version: ${{ github.ref_name }}
     secrets: inherit

ARCHITECTURE.md

@@ -0,0 +1,137 @@
+# libhal device library architecture
+
+Version: 1
+
+This document goes over the layout and architecture of a libhal device library.
+libhal device libraries implement device drivers by utilizing libhal
+interfaces. For example, a typical accelerometer (acceleration sensor),
+communicates with a host CPU via the protocol I2C. In order for that driver to
+be able to communicate over i2c it must be provided with an i2c driver
+controlling the port the sensor is connected to. This is done like so:
+
+```C++
+class some_accelerometer {
+  some_accelerometer(hal::i2c& p_i2c, hal::byte p_address);
+};
+```
+
+## Making a new Device Driver
+
+To make your own libhal library:
+
+1. Press the green "Use this Template" button then press the "Create a new
+   repository".
+2. Name it `libhal-<insert_device_name>` and replace `<insert_device_name>` with
+   the name of the device's family. For exmaple, if you want to make a library
+   for the MPU series of IMUs then call it `libhal-mpu`.
+3. Choose where to put the repo under,
+4. Go to `settings` > `Pages` > `Build and deployment` > `Source` and set the
+   source to `Github Actions`.
+5. Go to `Pull Requests` and merge the library rename pull request.
+6. Done!
+
+## Layout of the Directory
+
+### `.github/workflows/`
+
+This directory contains GitHub Actions workflow files for continuous integration
+(CI) and other automated tasks. The workflows currently included are:
+
+- `deploy.yml`: This workflow is used for deploy released versions of the code
+  to the JFrog artifactory. See the section:
+- `ci.yml`: This workflow runs the CI pipeline, which includes building the
+  project, running tests, and deploying the library to the `libhal-trunk`
+  package repository.
+- `take.yml`: This workflow is responsible for the "take" action, which assigns
+  commits to
+- `update_name.yml`: This workflow updates the name of the repository when it's
+  used as a template for a new repository.
+
+### `conanfile.py`
+
+This is a [Conan](https://conan.io/) recipe file. Conan is a package manager for
+C and C++ that helps manage dependencies in your project. This file defines how
+Conan should build your project and its dependencies.
+
+### `CMakeList.txt`
+
+The root CMake build script for the library. It contains a call to the
+[`libhal-cmake-util`](https://github.com/libhal/libhal-cmake-util) function
+[`libhal_test_and_make_library()`](https://github.com/libhal/libhal-cmake-util?tab=readme-ov-file#libhal_test_and_make_library).
+
+### `datasheets/`
+
+This directory is intended for storing data sheets related to the device that
+the library is being built for. By default this will contain a placeholder file,
+`put_datasheets_here.md`. This directory is meant to be a reference for library
+developers and potentially users of the library, to gain information about how
+the device behaves.
+
+Many data sheets are subject to copyright and that must be considered when
+adding the datasheet to a libhal repo. If the datasheet cannot be redistributed
+on the repo for copyright and/or license reasons, then a markdown file with a
+link to the datasheet (and potentially mirrors of it) is an acceptable
+alternative.
+
+### `demos/`
+
+This directory contains demonstration applications showing how to use the device
+library. It includes:
+
+- `resource_list.hpp`: A header file defining the resource list required for
+  the demo applications.
+- `main.cpp`: The main entry point for the demo applications.
+- `platforms/lpc4074.cpp` and `platforms/lpc4078.cpp`: Platform-specific
+  implementations for the demo applications.
+- `CMakeLists.txt`: Build file using the
+  [`libhal_build_demos`](https://github.com/libhal/libhal-cmake-util?tab=readme-ov-file#libhal_test_and_make_library)
+  function from
+  [`libhal-cmake-util`](https://github.com/libhal/libhal-cmake-util).
+
+### `include/libhal-__device__/`
+
+This directory contains the header files for the device library. This contains
+the public APIs. Try and keep the public APIs as minimal as possible as
+removing or changing something from this area will result in either an API or
+ABI break.
+
+### `src/`
+
+This directory contains the source files for the device library. Implementation
+details for the device library and any other private support libraries are
+written here.
+
+### `test_package/`
+
+This directory contains a test package for the Conan recipe. This tests that
+the Conan recipe is working correctly. The test package doesn't have to do
+anything fancy. It just exists to ensure that the device library can be a
+dependency of an application and successfully build. Make sure to at least
+include one file from the public includes of this repo in order to determine
+that your headers work. If possible, create an object or run a function in the
+code to ensure that your APIs and types can be used in the package.
+
+### `tests/`
+
+This directory contains tests for the device library. It will always contain a `main.test.cpp` which is the entry point for the tests.
+
+## How to Deploy Binaries for a Release
+
+1. On Github, click on the "Releases" button
+2. Press "Draft a new release"
+3. For the tag drop down, provide a version. This version should be in the
+   [SEMVER](https://semver.org/) format like so "1.0.0". No "v1.0.0" or "1.0.
+   0v" or anything like that.
+4. Press "Create New Tag" on the bottom of the drop down to create a tag for
+   this release.
+5. Press "Generate Notes" to add release notes to the release. Feel free to add
+   additional notes you believe are useful to developers reading over these
+   changes.
+6. Press "Public Release"
+7. The release should now exist in the "releases" section of the repo.
+8. Go to Actions and on the left hand bar, press "🚀 Deploy"
+9. Press "Run Workflow"
+10. For the "Use workflow from" drop down, press it and select "tag" then the
+    "tag" version of your release.
+11. Finally press "Run Workflow" and the `deploy.yml` action will build your
+    device driver for all of the available libhal platforms and deploy to the JFrog Artifactory binary repository.

README.md

@@ -1,112 +1,68 @@
 # libhal-__device__
 
 [![✅ Checks](https://github.com/libhal/libhal-__device__/actions/workflows/ci.yml/badge.svg)](https://github.com/libhal/libhal-__device__/actions/workflows/ci.yml)
-[![Coverage](https://libhal.github.io/libhal-__device__/coverage/coverage.svg)](https://libhal.github.io/libhal-__device__/coverage/)
 [![GitHub stars](https://img.shields.io/github/stars/libhal/libhal-__device__.svg)](https://github.com/libhal/libhal-__device__/stargazers)
 [![GitHub forks](https://img.shields.io/github/forks/libhal/libhal-__device__.svg)](https://github.com/libhal/libhal-__device__/network)
 [![GitHub issues](https://img.shields.io/github/issues/libhal/libhal-__device__.svg)](https://github.com/libhal/libhal-__device__/issues)
 
-libhal compatible device library for the __device__ device.
+libhal compatible device library for the __device__ family of devices.
 
-## Contributing
-
-See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.
-
-## License
-
-Apache 2.0; see [`LICENSE`](LICENSE) for details.
-
-
-**AFTER CLONING DELETE THE SECTION BELOW AND ADD YOUR OWN CONTENT**.
-
-## Making a new device driver
+## 🏗️ Building Demos
 
-To make your own libhal library:
+To build demos, start at the root of the repo and execute the following command:
 
-1. press the green "Use this Template" button then
-2. press the "Create a new repository".
-3. Name it `libhal-<insert_device_name>` and replace `<insert_device_name>` with
-  the name of the device's family. For exmaple, if you want to make a library
-  for the MPU series of IMUs then call it `libhal-mpu`.
-4. Choose where to put the repo under,
-5. Go to `settings` > `Pages` > `Build and deployment` > `Source` and set the
-  source to `Github Actions`.
-6. Go to `Pull Requests` and merge the library rename pull request.
-7. Done!
+```bash
+conan build demos -pr lpc4078 -pr arm-gcc-12.3
+```
 
-## About the libhal-device template
+or for the `lpc4074`
 
-The libhal-__device__ repository is a template for creating device libraries in
-the libhal ecosystem. It provides a structured layout and a set of files to help
-you get started with creating your own device library.
+```bash
+conan build demos -pr lpc4074 -pr arm-gcc-12.3
+```
 
-## .github/workflows
+or for the `stm32f103c8`
 
-This directory contains GitHub Actions workflow files for continuous integration
-(CI) and other automated tasks. The workflows currently included are:
+```bash
+conan build demos -pr stm32f103c8 -pr arm-gcc-12.3
+```
 
-- `ci.yml`: This workflow runs the CI pipeline, which includes
-  building the project, running tests, and deploying the library to the
-  `libhal-trunk` package repository.
-- `take.yml`: This workflow is responsible for the "take" action, which assigns
-  commits to
-- `update_name.yml`: This workflow updates the name of the repository when it's
-  used as a template for a new repository.
+## 📦 Building The Library Package Demos
 
-## conanfile.py
+To build demos, start at the root of the repo and execute the following command:
 
-This is a [Conan](https://conan.io/) recipe file. Conan is a package manager for
-C and C++ that helps manage dependencies in your project. This file defines how
-Conan should build your project and its dependencies.
+```bash
+conan create . -pr lpc4078 -pr arm-gcc-12.3 --version=latest
+```
 
-## datasheets
+To compile the package for the `stm32f103c8` or `lpc4074`, simply replace the `lpc4078` profile with the appropriate profile name. For example:
 
-This directory is intended for storing datasheets related to the device that the
-library is being built for. It currently contains a placeholder file,
-`put_datasheets_here.md`.
+```bash
+conan create . -pr stm32f103c8 -pr arm-gcc-12.3 --version=latest
+```
 
-Many datasheets are subject to copyright and that must be considered when adding
-the datasheet to a libhal repo. If the datasheet cannot be redistributed on the
-repo for copyright and/or license reasons, then a markdown file with a link to
-the datasheet (and potentially mirrors of it) is an acceptable alternative.
+> [!NOTE]
+> If you are developing the code, and simply need to test that it builds and
+> that tests pass, use `conan build .` vs `conan create .`. This will build the
+> package locally in the current directory. You'll find the contents in the
+> `build/` directory at the root of the repo. Now links will point to the code
+> in the repo and NOT the conan package directory.
 
-## demos
+## 📋 Adding `libhal-__device__` to your project
 
-This directory contains demonstration applications showing how to use the device
-library. It includes:
+Add the following to your `requirements()` method:
 
-- `applications/__device__.cpp`: A sample application demonstrating usage of the
-  device library.
-- `hardware_map.hpp`: A header file defining the hardware map for the demo
-  applications.
-- `main.cpp`: The main entry point for the demo applications.
-- `platforms/lpc4074.cpp` and `platforms/lpc4078.cpp`: Platform-specific
-  implementations for the demo applications.
+```python
+    def requirements(self):
+        self.requires("libhal-__device__/[^1.0.0]")
+```
 
-## include/libhal-__device__
+Replace version `1.0.0` with the desired version of the library.
 
-This directory contains the header files for the device library. It currently
-includes `__device__.hpp`, which is a placeholder for the main header file of
-your device library.
-
-## src
-
-This directory contains the source files for the device library. It currently
-includes `__device__.cpp`, which is a placeholder for the main source file of
-your device library.
-
-## test_package
-
-This directory contains a test package for the Conan recipe. It includes a
-simple application that uses the device library, which helps verify that the
-Conan recipe is working correctly.
-
-## tests
+## Contributing
 
-This directory contains tests for the device library. It includes:
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.
 
-- `__device__.test.cpp`: A placeholder for tests for the device library.
-- `main.test.cpp`: The main entry point for the tests.
+## License
 
-Remember to replace all instances of `__device__` with the actual name of the
-device that your library is being built for.
+Apache 2.0; see [`LICENSE`](LICENSE) for details.

conanfile.py

@@ -26,7 +26,7 @@ class libhal___device___conan(ConanFile):
     topics = ("__device__", "libhal", "driver")
     settings = "compiler", "build_type", "os", "arch"
 
-    python_requires = "libhal-bootstrap/[^2.0.0]"
+    python_requires = "libhal-bootstrap/[^3.0.0]"
     python_requires_extend = "libhal-bootstrap.library"
 
     def requirements(self):

demos/applications/__device__.cpp

@@ -15,20 +15,22 @@
 #include <libhal-util/serial.hpp>
 #include <libhal-util/steady_clock.hpp>
 
-#include "../hardware_map.hpp"
+#include "../resource_list.hpp"
 
-void application(hardware_map_t& p_map)
+void application(resource_list& p_map)
 {
   using namespace std::chrono_literals;
   using namespace hal::literals;
 
   auto& clock = *p_map.clock;
   auto& console = *p_map.console;
+  auto& led = *p_map.led;
 
   hal::print(console, "Demo Application Starting...\n\n");
 
   while (true) {
-    hal::delay(clock, 500ms);
     hal::print(console, "Hello, world\n");
+    led.level(!led.level());  // Toggle LED
+    hal::delay(clock, 500ms);
   }
 }

demos/conanfile.py

@@ -15,7 +15,7 @@
 
 
 class demos(ConanFile):
-    python_requires = "libhal-bootstrap/[^2.0.0]"
+    python_requires = "libhal-bootstrap/[^3.0.0]"
     python_requires_extend = "libhal-bootstrap.demo"
 
     def requirements(self):