diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md new file mode 100644 index 0000000..9dc8b5c --- /dev/null +++ b/CODE-OF-CONDUCT.md @@ -0,0 +1,85 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity +and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting +via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement. All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. +Translations are available at https://www.contributor-covenant.org/translations. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ac59c96 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,412 @@ +# Contributing to Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss Arduino projects + +Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community. + +## Ground rules & expectations + +Before we get started, here are a few things we expect from you (and that you should expect from others): + +- Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct. +- This project is released with a [Contributor Code of Conduct](CODE-OF-CONDUCT.md). By participating in this project, you agree to abide by its terms. +- Please ensure that your contribution complies with this document. If it does not, you will need to address and fix all issues before we can merge your contribution. +- When adding content, please consider if it is widely valuable. + +## Overview + +Being an Open Source project, everyone can contribute, provided that you respect the following points: + +- Before contributing any code, the author must make sure all the tests work (see below how to launch the tests). +- Developed code must adhere to the syntax guidelines enforced by the linters. +- Code must be developed following the [SemVer (Semantic Versioning 2.0.0)](https://semver.org/) branching model. +- For any new feature added, unit tests must be provided, following the example of the ones already created. + +## How to contribute + +If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question. + +If you don't see your idea listed, and you think it fits into the goals of this guide, do one of the following: + +- Bug Report +- Feature Proposal +- Feature Request +- Vulnerability Report + +### Repository Issues + +The first step is to head to our repository issues tab and decide how you would like to contribute. + +![Repository Issues](assets/images/repo-issues.jpg) + +### Bug reports + +![Bug Reports](assets/images/bug-report.jpg) + +If you would like to contribute bug fixes or make the team aware of bugs you have identified in the project, please raise a **Bug report** issue in the [issues section](issues/new/choose) section. A template is provided that will allow you to provide your suggestions for your bug report / bug fix(es) which will be reviewed by the team. + +Bug fix issues are the first step to creating a pull request for bug fixes, once you have created your issue and it has been approved you can proceed with your bug fixes. + +### Feature proposals + +![Feature Proposals](assets/images/feature-proposals.jpg) + +If you would like to contribute new features to the project, please raise a **Feature proposal** issue in the [issues section](issues/new/choose) section. A template is provided that will allow you to provide your suggestions for your feature proposal. + +Feature proposal issues are the first step to creating a pull request for feature proposals, once you have created your issue and it has been approved you can proceed with your feature proposal. + +### Feature requests + +![Feature requests](assets/images/feature-request.jpg) + +If you would like to suggest a new feature/new features for this project, please raise a **Feature request** issue in the [issues section](issues/new/choose) section. A template is provided that will allow you to provide your suggestions for your feature request. + +### Community + +Discussions about the Open Source Guides take place on this repository's +[Issues](issues) and [Pull Requests](pulls) sections, or the [discussions](discussions). Anybody is welcome to join these conversations. + +Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation. + +### Getting Started + +In order to start contributing: + +![Fork](assets/images/fork.jpg) + +1. Fork this repository clicking on the "Fork" button on the upper-right area of the page. + +2. Clone your just forked repository: + +```bash +git clone https://github.com/YourAccount/HIAS-ESP32-PIR-Sensor.git +``` + +3. Add the main HIAS-ESP32-PIR-Sensor repository as a remote to your forked repository: + +```bash +git remote add remote https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor.git +``` + +Before starting your contribution, remember to synchronize the latest `dev` branch in your forked repository with the `dev` branch in the main HIASHDI repository as specified by the **CURRENT DEV BRANCH** badge in the repository [README](README.md). To do this, use following these steps + +1. Change to your local `dev` branch (in case you are not in it already): + +```bash +git checkout 2.0.0 +``` + +2. Fetch the remote changes: + +```bash +git fetch remote +``` + +3. Merge them: + +```bash +git rebase HIAS-ESP32-PIR-Sensor/2.0.0 +``` + +Contributions following these guidelines will be added to the `dev` branch, and released in the next version. The release process is explained in the _Releasing_ section below. + +### Documentation + +Changes you make to the code in the repository or new projects that you make should be supported with documentation added to the **docs** directory. + +It is the contributor's responsibility to ensure that the documentation is up to date. If you are contributing to an existing repository you will ensure that these documents are updated and/or added to to reflect your changes. + +We use [MKDocs](https://www.mkdocs.org/) along with [Read the Docs](https://docs.readthedocs.io/en/stable/index.html). Use the [Getting Started with MkDocs](https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html) guide to find out how to update/create documentation for the project. + +### Repository structure + +Repository structures for HIAS Arduino projects **must be followed exactly** for all contributions. Pull Requests that do not follow this structure will be rejected and closed with no further discussion. + +``` +- Project Root (Directory) + - arduino (Directory) + - HIAS-ESP32-PIR-Sensor (Directory) + - HIAS-ESP32-PIR-Sensor.ino (File) + - assets (Directory) + - images (Directory) + - project-banner.jpg (Image) + - bug-report.jpg (Image) + - feature-proposal.jpg (Image) + - feature-request.jpg (Image) + - fork.jpg (Image) + - repo-issues.jpg (Image) + - docs (Directory) + - img (Directory) + - project-banner.jpg (image) + - installation (Directory) + - installation.md (File) + - index.md (File) + - CODE-OF-CONDUCT.md (File) + - CONTRIBUTING.md (File) + - LICENSE (File) + - mkdocs.yml (File) + - README.md (File) +``` + +**Directories and files may be added to the above structure as required, but none must be removed.** + +### Project Images + +Images used in the project must be **jpg**. You must own rights to images you upload to the project, or include attribution. Contributors are solely responsible for any images they publish to our Github. + +### Naming Scheme + +The following naming scheme must be used: + +- **Directories:** Snake case (snake_case) +- **Files:** Spinal case (spinal-case) +- **Images:** Spinal case (spinal-case) + +Please use descriptive but short names, and make sure to not use spaces in directory and file names. + +### Headers + +All Arduino files must include the following header, replacing **Program Title** with a short but descriptive title for the module, and **Program Description** with a paragraph explaining what the module is for. + +``` +/* Program Title + + Program Description + + MIT License + + Copyright (c) 2021 Asociación de Investigacion en Inteligencia Artificial + Para la Leucemia Peter Moss + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files(the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and / or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + + Contributors: + - +*/ +``` + +#### Attribution + +- When you create a new file you should add your name to the **Contributors** section. +- When you make a change to an existing file you should add your name to the **Contributors** section below existing contributors. You must not remove existing contributors from a header or README. + +### Footers + +All READMEs and documentation should include the following footer: + +``` +# Contributing +Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community. + +Please read the [CONTRIBUTING](CONTRIBUTING.md "CONTRIBUTING") document for a full guide to forking our repositories and submitting your pull requests. You will also find our code of conduct in the [Code of Conduct](CODE-OF-CONDUCT.md) document. + +## Contributors +- [Adam Milton-Barker](https://www.leukemiaairesearch.com/association/volunteers/adam-milton-barker "Adam Milton-Barker") - [Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss](https://www.leukemiaresearchassociation.ai "Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss") President/Founder & Lead Developer, Sabadell, Spain + +  + +# Versioning +We use [SemVer](https://semver.org/) for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](CONTRIBUTING.md "CONTRIBUTING") for more info on how to submit bugs, feature requests and proposals. +``` + +Remember to use **relative URLs**, and in the case of footers in the [docs](docs) folder, you must us **absolute URLs**. + +The contributors section should include a list of contributors that have contributed to the related document. In the case of the README footer, the Contributors section should include a list of contributors that have contributed to **any** part of the project. + +You should add your details below existing contributors. Details should include: + +- Name +- Company/University etc +- Position +- City +- Country + +### Branching model + +There are one special branch in the repository: + +- `main`: contains the tagged and released version +- `1.0.0`: is the current `dev` branch and contains the latest development code. New features and bugfixes are always merged to current `dev` branch. + +In order to start developing a new feature or refactoring, a new branch will be created following the SemVer scheme: + +Given a version number MAJOR.MINOR.PATCH, increment the: + +- `MAJOR` version when you make incompatible code changes, +- `MINOR` version when you add functionality in a backwards compatible manner, and +- `PATCH` version when you make backwards compatible bug fixes. + +- If `MAJOR` is 0, then Minor could mean the version is not backwards compatible +- If `MINOR` is 1, this means the release is stable. + +The branch will be created by our team depending on the nature of your issue. Once the new functionality has been completed, a Pull Request will be created from the feature branch to the relevant branch. Remember to check both the linters, and +the tests before creating the Pull Request. + +In order to contribute to the repository, the same scheme should be replicated in the forked repositories, so the new features or fixes should all come from the current version of `dev` branch and end up in the current `dev` branch again. + +### CII Best Practices + +All projects must align with the [CII Best Practice](https://www.construction-institute.org/resources/knowledgebase/best-practices). + +### Changelog + +The project contains a changelog that is automatically created from the description of the Pull Requests that have been merged into develop, thanks to the [Release Drafter GitHub action](https://github.com/marketplace/actions/release-drafter). + +### Releasing + +The process of making a release simply consists of creating the release in Github and providing the new tag name, this task is carried out by our team. + +### Version numbers + +The version number will change for each release, following the SemVer scheme described previously. + +### Bugfix in releases + +When a bug is found affecting a release, a branch will be created from the `main` branch. As a part of the patch, the release version will be increased in it's last number (Z). The patch then will be merged (via pull request (PR)) to the `main` branch, and a new version will be released. + +### Commits + +Commits should be [atomic](https://en.wikipedia.org/wiki/Atomic_commit), make commits to your fork until you have resolved/completed the work specified in your issue before submitting your PR, this keeps an easy to follow history of what work has been carried out and makes the review process easier and quicker + +When making a commit, the subjects of each commit should be as follows, where XXX represents the issue number: + +#### Commit Title + +##### Bug Fixes + +- fix #xxx Issue Name +- fixes #xxx Issue Name +- fixed #xxx Issue Name + +##### Partial Resolutions + +- partially resolves #xxx Issue Name +- partially resolved #xxx Issue Name + +##### Resolution + +- resolves #xxx Issue Name +- resolved #xxx Issue Name + +##### Alignment + +- aligns with #xxx Issue Name + +##### Closure + +- close #xxx Issue Name +- closes #xxx Issue Name +- closed #xxx Issue Name + +#### Commit Description + +Your commit description should include a detailed description of the changes that have been made. + +#### Committing + +When you are ready to commit, you should do the following: + +##### Show The Status Of All Changed/Added/Deleted files + +``` +git status +``` + +##### Diff + +You may want to check the differences between changed files, you can do this using the following command. + +``` +git diff +``` + +##### Add All Changes + +The following will add all changes shown by git status to your commit. + +``` +git add . +``` + +##### Add One Or More Changes + +``` +git add file1 file2 file5 +``` + +##### Commit Added Changes + +Commit your added changes to your local repository, remember to follow the [Commit Title](#commit-title) & [Commit Description](#commit-description) guides above. + +To create your commit with both a title and description, use the following command which states the commit fixes issue ID 1 and provides a detailed description: + +``` +git commit -m "fixes #1" -m "Fixes the documentation typos described in issue #1" +``` + +### Push Your Changes + +When you have made your changes, ensured you have aligned with the procedures in this document, and made your commits to your local repository aligning with the guide above, you need to push your changes to your forked repository. + +Push changes to your fork by using the following command: + +``` +git push +``` + +### Pull Request protocol + +Contributions to the HIASHDI repository are done using a PR. The detailed "protocol" used in such PR is described below: + +* Direct commits to main or develop branches (even single-line modifications) are not allowed. Every modification has to come as a PR to the latest `dev branch` +* PRs implement/fix submitted issues, the issue number has to be referenced in the subject of the relevant commit and PR +* Anybody is welcome to provide comments to the PR (either direct comments or using the review feature offered by Github) +* Use *code line comments* instead of *general comments*, for traceability reasons (see comments lifecycle below) +* Comments lifecycle + * Comment is created, initiating a *comment thread* + * New comments can be added as responses to the original one, starting a discussion + * After discussion, the comment thread ends in one of the following ways: + * `Fixed in ` in case the discussion involves a fix in the PR branch (which commit hash is included as reference) + * `NTC`, if finally nothing needs to be done (NTC = Nothing To Change) +* PR can be merged when the following conditions are met: + * All comment threads are closed + * All the participants in the discussion have provided a `LGTM` general comment (LGTM = Looks good to me) + * All documentation has been updated to reflect your changes. + * No proprietory software or images have been added. + +* Self-merging is not allowed (except in rare and justified circumstances) + +Some additional remarks to take into account when contributing with new PRs: + +* PR must include not only code contributions, but their corresponding pieces of documentation (new or modifications to existing one) and tests +* Documentation must be added to the **docs** folder +* In the case empty directories need to be uploaded, add a `.gitkeep` file inside. +* The project banner is included in all documentation +* Contributing, Versioning, Licensing, Bugs/Issues footer is included in all information +* Contributors have been added to all Contributors footers +* PR modifications must pass full regression based on existing tests in addition to whichever new test added due to the new functionality +* PR should be of an appropriated size that makes review achievable. Too large PRs could be closed with a "please, redo the work in smaller pieces" without any further discussion \ No newline at end of file diff --git a/LICENSE b/LICENSE index ff6c301..1f7fb6f 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2021 Peter Moss MedTech Research Project +Copyright (c) 2021 Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 32936f7..1119e89 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,75 @@ -# HIAS-ESP32-PIR-Sensor -A HIAS BLE server hosted on an ESP32 that provides readings from an PIR sensor. +# Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss +## HIAS ESP32 PIR Sensor + +![HIAS ESP32 PIR Sensor](assets/images/project-banner.jpg) + +[![CURRENT RELEASE](https://img.shields.io/badge/CURRENT%20RELEASE-1.0.0-blue.svg)](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/tree/1.0.0) [![UPCOMING RELEASE](https://img.shields.io/badge/CURRENT%20DEV%20BRANCH-2.0.0-blue.svg)](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/tree/2.0.0) [![Contributions Welcome!](https://img.shields.io/badge/Contributions-Welcome-lightgrey.svg)](CONTRIBUTING.md) [![Issues](https://img.shields.io/badge/Issues-Welcome-lightgrey.svg)](issues) + +[![Documentation Status](https://readthedocs.org/projects/hias-esp32-pir-sensor/badge/?version=latest)](https://hias-esp32-pir-sensor.readthedocs.io/en/latest/?badge=latest) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5088/badge)](https://bestpractices.coreinfrastructure.org/projects/5088) + +![Unit Tests](https://img.shields.io/badge/Unit%20Tests-TODO-red) +![Functional Tests](https://img.shields.io/badge/Functional%20Tests-TODO-red) + + [![LICENSE](https://img.shields.io/badge/LICENSE-MIT-blue.svg)](LICENSE) + +  + +# Introduction + +PIR sensors can play a large role in Internet of Things (IoT) security systems. This project shows the potential of using an ESP32 to host a Bluetooth Low Energy (BLE) server providing readings from a PIR sensor to a HIAS BLE IoT Agent. + +![HIAS ESP32 PIR Sensor](assets/images/hias-esp32-pir-sensor.gif) + +The server waits for a HIAS BLE IoT Agent to connect and provides it with the current reading of the PIR sensor. The BLE IoT Agent next verifies the server has permissions to store data on the HIAS network via the HIASBCH iotJumpWay permissions smart contract. + +![HIAS BLE Network](assets/images/hias-ble-network.jpg) + +Once the server is verified, the BLE IoT Agent processes the sensor data, updates the related contextual data and stores the data in the historical database. + +  + +# Hardware + + - [ESP32 Devkit](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html) + - [HC-SR501 PIR Sensor](https://www.amazon.es/Yizhet-HC-SR501-Infrared-Arduino-Raspberry/dp/B08B3L19QF) + - Wires + +  + +# Software + + - [Arduino IDE](https://www.arduino.cc/en/software) + - [Arduino-ESP32](https://github.com/espressif/arduino-esp32) + +  + +# Getting Started + +To set up and install your HIAS ESP32 PIR Sensor follow the following guides. + +- [Installation guide](docs/installation/installation.md) + +  + +# Contributing +Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community. + +Please read the [CONTRIBUTING](CONTRIBUTING.md "CONTRIBUTING") document for a full guide to contributing to our research project. You will also find our code of conduct in the [Code of Conduct](https://github.com/AIIAL/Contributing-Guide/blob/main/CODE-OF-CONDUCT.md) document. + +## Contributors +- [Adam Milton-Barker](https://www.leukemiaairesearch.com/association/volunteers/adam-milton-barker "Adam Milton-Barker") - [Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss](https://www.leukemiaresearchassociation.ai "Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss") President/Founder & Lead Developer, Sabadell, Spain + +  + +# Versioning +We use [SemVer](https://semver.org/) for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](CONTRIBUTING.md "CONTRIBUTING") for more info on how to submit bugs, feature requests and proposals. \ No newline at end of file diff --git a/arduino/HIAS-PIR-Sensor/HIAS-ESP32-PIR-Sensor.ino b/arduino/HIAS-PIR-Sensor/HIAS-ESP32-PIR-Sensor.ino new file mode 100644 index 0000000..2fd3386 --- /dev/null +++ b/arduino/HIAS-PIR-Sensor/HIAS-ESP32-PIR-Sensor.ino @@ -0,0 +1,192 @@ +/* HIAS ESP32 PIR Sensor + + A HIAS BLE server that provides readings from a PIR sensor. + + Based on https://github.com/nkolban/ESP32_BLE_Arduino/tree/master/examples/BLE_server_multiconnect + + MIT License + + Copyright (c) 2021 Asociación de Investigacion en Inteligencia Artificial + Para la Leucemia Peter Moss + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files(the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and / or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + + Contributors: + - Adam Milton-Barker +*/ + +#include +#include +#include +#include + +#include +#include + +struct Config { + String serviceUUID; + String characteristicUUID; + String deviceUUID; + String deviceName; +}; + +Config config; +int motion; + +const int LED = 2; +const int pirPin = 4; + +char bleBuffer[200] = {0}; + +BLEServer* pServer = NULL; +BLECharacteristic* pCharacteristic = NULL; +bool deviceConnected = false; +bool oldDeviceConnected = false; + +class DeviceBleCallbacks: public BLEServerCallbacks { + void onConnect(BLEServer* pServer) { + deviceConnected = true; + BLEDevice::startAdvertising(); + Serial.println("Client connected"); + digitalWrite(LED, HIGH); + }; + + void onDisconnect(BLEServer* pServer) { + deviceConnected = false; + Serial.println("Client disconnected"); + digitalWrite(LED, LOW); + } +}; + +void configs(Config &config) +{ + if (!SPIFFS.begin()) + { + Serial.println(F("Failed to mount SPIFFS")); + } + else + { + File file = SPIFFS.open("/config.json", FILE_READ); + if (!file) + { + return; + } + else + { + StaticJsonDocument<1048> doc; + DeserializationError error = deserializeJson(doc, file); + if (error) + { + Serial.println(error.c_str()); + } + else + { + config.serviceUUID = doc["ble"]["service"].as(); + config.characteristicUUID = doc["ble"]["characteristic"].as(); + config.deviceUUID = doc["iotJumpWay"]["device"].as(); + config.deviceName = doc["iotJumpWay"]["deviceName"].as(); + Serial.println(F("Configuration loaded!")); + } + } + file.close(); + } +} + +void setup() { + Serial.begin(115200); + + if(!SPIFFS.begin(true)){ + return; + } + + configs(config); + + // Set ultrasonic trigger and echo pins + pinMode(pirPin, INPUT); + + // Set LED pin + pinMode(LED, OUTPUT); + + // Create the BLE Device + BLEDevice::init(config.deviceName.c_str()); + + // Create the BLE Server + pServer = BLEDevice::createServer(); + pServer->setCallbacks(new DeviceBleCallbacks()); + + // Create the BLE Service + BLEService *pService = pServer->createService(config.serviceUUID.c_str()); + + // Create a BLE Characteristic + pCharacteristic = pService->createCharacteristic( + config.characteristicUUID.c_str(), + BLECharacteristic::PROPERTY_READ | + BLECharacteristic::PROPERTY_WRITE | + BLECharacteristic::PROPERTY_NOTIFY | + BLECharacteristic::PROPERTY_INDICATE + ); + + // Create a BLE Descriptor + pCharacteristic->addDescriptor(new BLE2902()); + + // Start the service + pService->start(); + + // Start advertising + BLEAdvertising *pAdvertising = BLEDevice::getAdvertising(); + pAdvertising->addServiceUUID(config.serviceUUID.c_str()); + pAdvertising->setScanResponse(false); + pAdvertising->setMinPreferred(0x0); + BLEDevice::startAdvertising(); + Serial.println("Awaiting client connection..."); +} + +int getReadings(){ + motion = digitalRead(pirPin); +} + +void loop() { + + // Send measurement to client + if (deviceConnected) { + String sendString = "{\"EntityType\":\"Device\",\"Entity\":\"" + config.deviceUUID + "\",\"Sensor\":\"" + config.deviceName + "\",\"Type\":\"Motion\",\"Value\":\"" + String(motion) + "\",\"Message\":\"Current motion\"}"; + memset(bleBuffer, 0, 200); + memcpy(bleBuffer, (char*)sendString.c_str(), 200); + pCharacteristic->setValue(bleBuffer); + pCharacteristic->notify(); + String message = "Sent " + sendString + " to client"; + Serial.println(F(message.c_str())); + } + + // Connection + if (deviceConnected && !oldDeviceConnected) { + oldDeviceConnected = deviceConnected; + } + + // Disconnection + if (!deviceConnected && oldDeviceConnected) { + delay(500); + pServer->startAdvertising(); + Serial.println("Client disconnected. Began advertising"); + oldDeviceConnected = deviceConnected; + } + + // Get current distance measurement + getReadings(); +} diff --git a/arduino/HIAS-PIR-Sensor/data/.itkeep b/arduino/HIAS-PIR-Sensor/data/.itkeep new file mode 100644 index 0000000..e69de29 diff --git a/assets/images/bug-report.jpg b/assets/images/bug-report.jpg new file mode 100644 index 0000000..05cf23c Binary files /dev/null and b/assets/images/bug-report.jpg differ diff --git a/assets/images/feature-proposals.jpg b/assets/images/feature-proposals.jpg new file mode 100644 index 0000000..8e01473 Binary files /dev/null and b/assets/images/feature-proposals.jpg differ diff --git a/assets/images/feature-request.jpg b/assets/images/feature-request.jpg new file mode 100644 index 0000000..d80541c Binary files /dev/null and b/assets/images/feature-request.jpg differ diff --git a/assets/images/fork.jpg b/assets/images/fork.jpg new file mode 100644 index 0000000..c9f50b6 Binary files /dev/null and b/assets/images/fork.jpg differ diff --git a/assets/images/hias-ble-network.jpg b/assets/images/hias-ble-network.jpg new file mode 100644 index 0000000..25030d6 Binary files /dev/null and b/assets/images/hias-ble-network.jpg differ diff --git a/assets/images/hias-esp32-pir-sensor.gif b/assets/images/hias-esp32-pir-sensor.gif new file mode 100644 index 0000000..04aa8f6 Binary files /dev/null and b/assets/images/hias-esp32-pir-sensor.gif differ diff --git a/assets/images/project-banner.jpg b/assets/images/project-banner.jpg new file mode 100644 index 0000000..b97220c Binary files /dev/null and b/assets/images/project-banner.jpg differ diff --git a/assets/images/repo-issues.jpg b/assets/images/repo-issues.jpg new file mode 100644 index 0000000..2a9fc9a Binary files /dev/null and b/assets/images/repo-issues.jpg differ diff --git a/docs/img/arduino-ide.jpg b/docs/img/arduino-ide.jpg new file mode 100644 index 0000000..ecf1c9b Binary files /dev/null and b/docs/img/arduino-ide.jpg differ diff --git a/docs/img/arduino-serial-monitor.jpg b/docs/img/arduino-serial-monitor.jpg new file mode 100644 index 0000000..8146173 Binary files /dev/null and b/docs/img/arduino-serial-monitor.jpg differ diff --git a/docs/img/hias-ble-network.jpg b/docs/img/hias-ble-network.jpg new file mode 100644 index 0000000..25030d6 Binary files /dev/null and b/docs/img/hias-ble-network.jpg differ diff --git a/docs/img/hias-device-create.jpg b/docs/img/hias-device-create.jpg new file mode 100644 index 0000000..8207363 Binary files /dev/null and b/docs/img/hias-device-create.jpg differ diff --git a/docs/img/hias-device-edit.jpg b/docs/img/hias-device-edit.jpg new file mode 100644 index 0000000..130ddb9 Binary files /dev/null and b/docs/img/hias-device-edit.jpg differ diff --git a/docs/img/hias-device-list.jpg b/docs/img/hias-device-list.jpg new file mode 100644 index 0000000..68ad6de Binary files /dev/null and b/docs/img/hias-device-list.jpg differ diff --git a/docs/img/hias-esp32-pir-sensor-fritzing.jpg b/docs/img/hias-esp32-pir-sensor-fritzing.jpg new file mode 100644 index 0000000..f8b46f9 Binary files /dev/null and b/docs/img/hias-esp32-pir-sensor-fritzing.jpg differ diff --git a/docs/img/hias-esp32-pir-sensor.gif b/docs/img/hias-esp32-pir-sensor.gif new file mode 100644 index 0000000..04aa8f6 Binary files /dev/null and b/docs/img/hias-esp32-pir-sensor.gif differ diff --git a/docs/img/project-banner.jpg b/docs/img/project-banner.jpg new file mode 100644 index 0000000..948881c Binary files /dev/null and b/docs/img/project-banner.jpg differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f513e27 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,65 @@ +# Documentation + +![HIAS ESP32 PIR Sensor](img/project-banner.jpg) + +  + +# Introduction + +PIR sensors can play a large role in Internet of Things (IoT) security systems. This project shows the potential of using an ESP32 to host a Bluetooth Low Energy (BLE) server providing readings from an PIR sensor to a HIAS BLE IoT Agent. + +![HIAS ESP32 PIR Sensor](img/hias-esp32-pir-sensor.gif) + +The server waits for a HIAS BLE IoT Agent to connect and provides it with the current reading of the PIR sensor. The BLE IoT Agent next verifies the server has permissions to store data on the HIAS network via the HIASBCH iotJumpWay permissions smart contract. + +![HIAS BLE Network](img/hias-ble-network.jpg) + +Once the server is verified, the BLE IoT Agent processes the sensor data, updates the related contextual data and stores the data in the historical database. + +  + +# Hardware + + - [ESP32 Devkit](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html) + - [HC-SR501 PIR Sensor](https://www.amazon.es/Yizhet-HC-SR501-Infrared-Arduino-Raspberry/dp/B08B3L19QF) + - Wires + +  + +# Software + + - [Arduino IDE](https://www.arduino.cc/en/software) + - [Arduino-ESP32](https://github.com/espressif/arduino-esp32) + +  + +# Getting Started + +To set up and install your HIAS ESP32 PIR Sensor follow the following guides: + +- [Installation guide](installation/installation.md) + +  + +# Contributing +Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community. + +Please read the [CONTRIBUTING](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to contributing to our research project. You will also find our code of conduct in the [Code of Conduct](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/CODE-OF-CONDUCT.md) document. + +## Contributors +- [Adam Milton-Barker](https://www.leukemiaairesearch.com/association/volunteers/adam-milton-barker "Adam Milton-Barker") - [Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss](https://www.leukemiaresearchassociation.ai "Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss") President/Founder & Lead Developer, Sabadell, Spain + +  + +# Versioning +We use [SemVer](https://semver.org/) for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/CONTRIBUTING.md "CONTRIBUTING") for more info on how to submit bugs, feature requests and proposals. \ No newline at end of file diff --git a/docs/installation/installation.md b/docs/installation/installation.md new file mode 100644 index 0000000..044b4f3 --- /dev/null +++ b/docs/installation/installation.md @@ -0,0 +1,147 @@ +# Installation Guide + +![HIAS ESP32 PIR Sensor](../img/project-banner.jpg) + +# Introduction +This guide will take you through the installation process for the **HIAS ESP32 PIR Sensor** project. + +  + +# Prerequisites +You will need to ensure you have the following prerequisites installed and set up. + +## Arduino + + - [Arduino IDE](https://www.arduino.cc/en/software) + - [Arduino-ESP32](https://github.com/espressif/arduino-esp32) + +## HIAS + - [HIAS Core](https://github.com/AIIAL/HIAS-Core) + - [HIASCDI](https://github.com/AIIAL/HIASCDI) + - [HIASHDI](https://github.com/AIIAL/HIASHDI) + - [HIASBCH](https://github.com/AIIAL/HIASBCH) + - [HIAS MQTT IoT Agent](https://github.com/AIIAL/HIAS-MQTT-IoT-Agent) + - [HIAS MQTT Blockchain Agent](https://github.com/AIIAL/HIASBCH-MQTT-Blockchain-Agent) + - [HIAS BLE IoT Agent](https://github.com/AIIAL/HIAS-BLE-IoT-Agent) + +  + +# Operating System +The HIAS ESP32 PIR Sensor installation guide is compatible with: + +- Windows +- Ubuntu + +  + +# Clone the repository + +Clone the [HIAS ESP32 PIR Sensor](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor " HIAS ESP32 PIR Sensor") repository from the [Peter Moss MedTech Research Project](https://github.com/AIIAL "Peter Moss MedTech Research Project") Github Organization. + +To clone the repository and install the project, make sure you have Git installed. Now navigate to the directory you would like to clone the project to and then use the following command. + +``` bash + git clone https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor.git +``` + +This will clone the HIAS ESP32 PIR Sensor repository. + +``` bash + ls +``` + +Using the ls command in your home directory should show you the following. + +``` bash + HIAS-ESP32-PIR-Sensor +``` + +Navigate to the **HIAS-ESP32-PIR-Sensor** directory, this is your project root directory for this tutorial. + +## Developer forks + +Developers from the Github community that would like to contribute to the development of this project should first create a fork, and clone that repository. For detailed information please view the [CONTRIBUTING](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/CONTRIBUTING.md "CONTRIBUTING") guide. You should pull the latest code from the development branch. + +``` bash + git clone -b "2.0.0" https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor.git +``` + +The **-b "2.0.0"** parameter ensures you get the code from the latest developer branch. Before using the below command please check our latest main branch in the button at the top of the project README. + +  + +# HIAS + +## HIAS Device + +![HIAS iotJumpWay Device List](../img/hias-device-list.jpg) + +This project is a HIAS iotJumpWay (network) device. To set up a HIAS network device visit your [HIAS Core](https://github.com/AIIAL/HIAS-Core) UI and navigate to **IoT -> Devices**, then click on the **+ CREATE** button at the top right of the device list. + +![HIAS iotJumpWay Device Create](../img/hias-device-create.jpg) + +Complete the form with the information about your HIAS ESP32 PIR Sensor. + +### Remember + +- Make sure to select **PIR Sensor** as a device sensor. +- Make sure to save the configuration provided once the device is created. + +## HIAS Device Configuration + +![HIAS iotJumpWay Device Configuration](../img/hias-device-edit.jpg) + +Once your HIAS device has been created, you will be able to access it via **IoT -> Devices**. At the top of the configuration pane you will see the **Device Configuration** download button. Download the configurationfile to the **arduino/HIAS-ESP32-PIR-Sensor/data** directory and save it as **config.json**. + +  + +# ESP32 + +Now you need to wire up your ultrasonic sensor to your ESP32. + +![ESP32 PIR Sensor](../img/hias-esp32-pir-sensor-fritzing.jpg) + +  + +# Arduino + +For this tutorial you need need **Arduino IDE 1.8.13**. You cannot use the **Arduino IDE 2.0 BETA** as it currently does not provide the **ESP32 Sketch Data Upload** feature. + +![Arduino IDE](../img/arduino-ide.jpg) + +Navigate to the **arduino/HIAS-PIR-Sensor** directory in your project root and double click the **HIAS-PIR-Sensor.ino** file to open it in Arduino IDE. + +Make sure you select the **DOIT ESP32 DEVKIT V1** board in **Tools** and select the correct **COM port** in the port settings. + +To upload the **config.json** file we downloaded from HIAS to the ESP32, click on **Tools -> ESP32 Sketch Data Upload**. This will upload the config file that will be used by the server during startup. + +![Arduino Serial Monitor](../img/arduino-serial-monitor.jpg) + +Finally, click on the **Upload** button in Arduino IDE and wait for the software to upload to your ESP32. Once the upload process has finished, open the **Serial Monitor**. + +If you already have the HIAS BLE IoT Agent running you will need to restart it so that it retrieves the updated BLE device list. Once you have restarted the HIAS BLE IoT Agent, you will be able to see the data that is being sent to the agent in the serial monitor. + +  + +# Contributing +Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community. + +Please read the [CONTRIBUTING](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to contributing to our research project. You will also find our code of conduct in the [Code of Conduct](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/CODE-OF-CONDUCT.md) document. + +## Contributors +- [Adam Milton-Barker](https://www.leukemiaairesearch.com/association/volunteers/adam-milton-barker "Adam Milton-Barker") - [Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss](https://www.leukemiaresearchassociation.ai "Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss") President/Founder & Lead Developer, Sabadell, Spain + +  + +# Versioning +We use [SemVer](https://semver.org/) for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor/blob/main/CONTRIBUTING.md "CONTRIBUTING") for more info on how to submit bugs, feature requests and proposals. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..9f4ba8c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,2 @@ +site_name: HIAS ESP32 PIR Sensor +site_url: https://github.com/AIIAL/HIAS-ESP32-PIR-Sensor