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 index 8719fb2..1f6ec83 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,163 +1,242 @@ -# Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss -## Contributing To Our Projects - -  +# Contributing to Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss 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. -The following is a guide on how to contribute to Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss Github projects and **_should be followed in all cases_**. +## Ground rules & expectations -  +Before we get started, here are a few things we expect from you (and that you should expect from others): -# Table Of Contents - -- [Repository Issues](#repository-issues) - - [Bug reports](#bug-reports) - - [Feature requests](#feature-requests) - - [Feature proposals](#feature-proposals) -- [Creating a fork of the repository](#creating-a-fork-of-the-repository) -- [Repository structure](#repository-structure) -- [Documentation](#documentation) -- [Installation Scripts](#documentation) -- [Naming](#documentation) -- [Attribution](#documentation) -- [.md Files](#documentation) -- [Push changes to forked repository](#documentation) -- [Pull requests](#documentation) -- [Pull requests process](#documentation) -- [Code of conduct](#documentation) - - [Our pledge](#documentation) - - [Our standards](#documentation) - - [Our responsibilities](#documentation) +- 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 -# Repository Issues +### 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.png) +![Repository Issues](assets/images/repo-issues.jpg) -## Bug reports +### Bug reports -![Bug Reports](assets/images/bug-report.png) +![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 requests +### Feature proposals -![Bug Reports](assets/images/feature-request.png) +![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. -## Feature proposals +### Community -![Bug Reports](assets/images/feature-proposals.png) +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. -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. +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 -# Creating a fork of the repository +In order to start contributing: -![Creating a fork of the repository](assets/images/fork.png) -If you are going to be contributing code or documentation to the repository you will need to make a fork of the current development branch. The current development branch will always be the highest branch or master. Once you have created a fork of the repository, you will be able to clone the repository to a location on your development machine using terminal and Git or Github Desktop if using Windows. +![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-AMQP-IoT-Agent.git +``` + +3. Add the main HIAS-AMQP-IoT-Agent repository as a remote to your forked repository: + +```bash +git remote add HIAS-AMQP-IoT-Agent https://github.com/AIIAL/HIAS-AMQP-IoT-Agent.git +``` + +Before starting your contribution, remember to synchronize the latest `dev` branch in your forked repository with the `dev` branch in the main HIAS-AMQP-IoT-Agent 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 HIAS-AMQP-IoT-Agent +``` -# Repository structure +3. Merge them: + +```bash +git rebase HIAS-AMQP-IoT-Agent/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 IoT Agents **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) - - config (Directory) * - - config.json (File) * - - credentials.json (File) * - - modules (Directory) * - - AbstractAgent.py (File) * - - AbstractData.py (File) * - - AbstractModel.py (File) * - - AbstractServer.py (File) * - - helpers.py (File) * - - data.py (File) * - - model.py (File) * - - mqtt.py (File) * - - server.py (File) * - - documentation (Directory) + - agent_modules (Directory) + - helpers.py (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) + - configuration (Directory) + - config.json (File) + - credentials.json (File) + - docs (Directory) + - img (Directory) + - project-banner.jpg (image) - installation (Directory) - - Ubuntu - - Windows - - Raspberry Pi OS - - logs (Directory) - - logfiles - - assets - - media - - images (Directory) - - videos (Directory) - - model - - data (Directory) * - - test (Directory) * - - train (Directory) * - - plots (Directory) * - - model.json (File) - - weights.h (File) + - ubuntu.md (File) + - usage (Directory) + - ubuntu.md (File) + - getting-started.md (File) + - index.md (File) - scripts - install.sh (File) + - service.sh (File) - agent.py (File) - - Project README (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.** -# Documentation +### Installation Scripts -All projects should have documentation, changes you make to the code in the repository or new projects that you make should also have documentation. In the structures above you can see the **Documentation** directories, and the **Installation** file. This installation file should contain a step by step guide to how to install your project, while directions of use will be a high level tutorial in your project README. If you are contributing an existing repository you will ensure that these documents are updated to reflect your changes. +The default installation script is [install.sh](scripts/install.sh) found in the [scripts](scripts) directory. -  +You must include the installation commands for all libraries for the project using apt/pip/make etc. Replace **# DEVELOPER TO ADD INSTALLATION COMMANDS FOR ALL REQUIRED LIBRARIES (apt/pip etc)** with the relevant installation commands. If you are contributing an existing repository you will ensure that these scripts are updated to reflect your changes. -# Installation Scripts +### Configuration -You will notice the **Scripts** directory above, this is home to any scripts that make it easier for the end use to set up and / or use your project. By default every project must have an installation script when installations are required. If you are contributing an existing repository you will ensure that these scripts are updated to reflect your changes. +The project configuration file [config.json](configuration/config.json) can be found in the [configuration](configuration) directory. -  +All configurable variables should be held within this file and used wherever relevant throughout the project. -# Naming +The [helpers file](modules/helpers.py) loads the configuration and makes it available as `helpers.confs`. -We use CamelCase for our directory and file names (except images), we would like this to stay uniform across all of our projects. Please use descriptive but short names where possible, and make sure you do not use spaces in directory and file names. +You may remove redundent objects/arrays/values. from the configuration and/or add new ones. -  +### Project Images -# Attribution +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. -Whenever relevant you should add yourself to the contributors section of the READMEs. If you have a public profile on the Peter Moss Leukemia AI Research website, you should use this in your link. Please see the contributing section of any of our READMEs for examples. +### Naming Scheme -  +The following naming scheme must be used: -# .md Files +- **Directories:** Snake case (snake_case) +- **Files:** Spinal case (spinal-case) +- **Images:** Spinal case (spinal-case) -Each .md file in the repository should use the same header. An example of this is as follows: +Please use descriptive but short names, and make sure to not use spaces in directory and file names. -``` -# Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss -## Acute Lymphoblastic Leukemia oneAPI Classifier +### Headers -![Acute Lymphoblastic Leukemia oneAPI Classifier](assets/images/all-oneapi-classifier-2020.png) -``` -If the .md file is the README in the project root, it should including the following markdown, ensuring the repository URLS and versions are correct. +All Python files must include the following header, replacing **Module Title** with a short but descriptive title for the module, and **Module Description** with a paragraph explaining what the module is for. ``` -[![CURRENT RELEASE](https://img.shields.io/badge/CURRENT%20RELEASE-0.0.0-blue.svg)](https://github.com/AIIAL/Acute-Lymphoblastic-Leukemia-oneAPI-Classifier/tree/0.0.0) [![UPCOMING RELEASE](https://img.shields.io/badge/CURRENT%20DEV%20BRANCH-0.1.0-blue.svg)](https://github.com/AIIAL/Acute-Lymphoblastic-Leukemia-oneAPI-Classifier/tree/0.1.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) [![LICENSE](https://img.shields.io/badge/LICENSE-MIT-blue.svg)](LICENSE) -``` +#!/usr/bin/env python3 +""" Module Title. + +Module 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 module you should add your name to the **Contributors** section. +- When you make a change to an existing module you should add your name to the **Contributors** section below existing contributors. You must not remove existing contributors from a header. + +### 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 information about our code of conduct on this page. +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 @@ -165,7 +244,7 @@ Please read the [CONTRIBUTING](CONTRIBUTING.md "CONTRIBUTING") document for a fu   # Versioning -We use SemVer for versioning. +We use [SemVer](https://semver.org/) for versioning.   @@ -178,110 +257,184 @@ This project is licensed under the **MIT License** - see the [LICENSE](LICENSE " 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. ``` -The project README contributors should contain a list of all contributors in the entire repository. +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. -# Push changes to forked repository +You should add your details below existing contributors. Details should include: -When you have made your changes, you need to push them to your forked repository. This process requires a commit with a message about what your commit is, and then finally a push to the repository which will place your changes or created files to your forked repository. +- Name +- Company/University etc +- Position +- City +- Country -Show the status of all changed/added files. +### Branching model -``` -git status -``` +There are one special branch in the repository: -You may want to do check the differences between changed files, you can do this using the following command. +- `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. -``` -git diff -``` +In order to start developing a new feature or refactoring, a new branch will be created following the SemVer scheme: -Add all changes ready to commit. (You may not want to add all changed files, in this case please follow instructions to add single files to commit that you were shown using git status). To repeat, the following will add all changes shown by using git status to your commit. +Given a version number MAJOR.MINOR.PATCH, increment the: -``` -git add . -``` +- `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. -Commit your changes. +- If `MAJOR` is 0, then Minor could mean the version is not backwards compatible +- If `MINOR` is 1, this means the release is stable. -``` -git commit -m "Your descriptive commit message" -``` +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. -Push changes to your fork. +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. -``` -git push -``` +### PEP 8 -- Style Guide for Python Code -You can also Github Desktop if on Windows as shown in the image above. +All Python projects must align with the [PEP 8 -- Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/). -  +### CII Best Practices -# Pull requests +All projects must align with the [CII Best Practice](https://www.construction-institute.org/resources/knowledgebase/best-practices). -When you are satisfied with your changes you can submit a pull request that will request that your changes be pulled into the latest development branch. +### Changelog -## Pull Request Process +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). -1. Ensure all documentation has been updated and matches the style of our repository layouts, including repository directory structures etc. -2. Add new README.md files for new directories / ** init **.py files for empty directories. -3. Ensure that your READMEs, documentation and code match the format/design of the rest of the repoistory. -4. Include the project header banner on all documentation pages / READMEs. -5. Incude the Contributing, Versioning, Licensing, Bugs/Issues information in all READMEs and documentation. -6. Do not ever upload licensed software or images that you do not own the rights to. -7. Submit your Pull Request with an accurate description of the changes you have made. -8. Your Pull Request will be reviewed by the team. +### 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. -# Code of conduct +### Version numbers -Please note we have a code of conduct, please follow it in all your interactions with the project. +The version number will change for each release, following the SemVer scheme described previously. -## Our Pledge +### Bugfix in releases -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. +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. -## Our Standards +### Commits -Examples of behavior that contributes to creating a positive environment include: +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 -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members +When making a commit, the subjects of each commit should be as follows, where XXX represents the issue number, # must : -Examples of unacceptable behavior by participants include: +#### Commit Title -- The use of sexualized language or imagery and unwelcome sexual attention or advances -- Trolling, insulting/derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or electronic address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a professional setting +##### Bug Fixes -## Our Responsibilities +- fix #xxx +- fixes #xxx +- fixed #xxx -Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. +##### Partial Resolutions -Project maintainers 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, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. +- partially resolves #xxx +- partially resolved #xxx -## Scope +##### Resolution -This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. +- resolves #xxx +- resolved #xxx -## Enforcement +##### Alignment -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at github@leukemiaresearchassociation.ai All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +- aligns with #xxx -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. +##### Closure -  +- close #xxx +- closes #xxx +- closed #xxx + +#### 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 +``` -# Attribution +##### 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 +``` -This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org/version/1/4), version 1.4. \ No newline at end of file +### Pull Request protocol + +Contributions to the HIAS-AMQP-IoT-Agent 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/README.md b/README.md index 330ac84..0e1b693 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss ## HIAS AMQP IoT Agent -![HIAS AMQP IoT AgentHIAS AMQP IoT Agent](assets/images/hias-amqp-iot-agent.jpg) +![HIAS AMQP IoT AgentHIAS AMQP IoT Agent](assets/images/project-banner.jpg) + +[![CURRENT RELEASE](https://img.shields.io/badge/CURRENT%20RELEASE-1.1.0-blue.svg)](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/tree/1.1.0) [![UPCOMING RELEASE](https://img.shields.io/badge/CURRENT%20DEV%20BRANCH-2.0.0-blue.svg)](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/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) [![LICENSE](https://img.shields.io/badge/LICENSE-MIT-blue.svg)](LICENSE) [![PEP8](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/) [![Documentation Status](https://readthedocs.org/projects/hias-amqp-iot-agent/badge/?version=latest)](https://hias-amqp-iot-agent.readthedocs.io/en/latest/?badge=latest) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4998/badge)](https://bestpractices.coreinfrastructure.org/projects/4998) -[![CURRENT RELEASE](https://img.shields.io/badge/CURRENT%20RELEASE-1.0.0-blue.svg)](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/tree/1.0.0) [![UPCOMING RELEASE](https://img.shields.io/badge/CURRENT%20DEV%20BRANCH-2.0.0-blue.svg)](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/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) [![LICENSE](https://img.shields.io/badge/LICENSE-MIT-blue.svg)](LICENSE)   @@ -36,7 +37,7 @@ The **HIAS AMQP IoT Agent** is a bridge between HIAS devices that support the AM # GETTING STARTED -To get started follow the [Getting Started](documentation/getting-started.md) guide. +To get started follow the [Getting Started](docs/getting-started.md) guide.   diff --git a/agent.py b/agent.py index 0f39b2b..b9ab093 100644 --- a/agent.py +++ b/agent.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 """ HIAS iotJumpWay Agent Abstract Class HIAS IoT Agents process all data coming from entities connected to the HIAS @@ -67,6 +67,30 @@ class Agent(AbstractAgent): def __init__(self, protocol): super().__init__(protocol) + def amqpConsumeSet(self): + """ Sets up the AMQP queue subscriptions. """ + + self.channel.basic_consume('Life', self.lifeCallback, + auto_ack=True) + self.channel.basic_consume('Statuses', self.statusCallback, + auto_ack=True) + self.channel.basic_consume('Sensors', self.sensorsCallback, + auto_ack=True) + self.helpers.logger.info("AMQP consume setup!") + + def amqpConsumeStart(self): + """ Starts consuming. """ + + self.helpers.logger.info("AMQP consume starting!") + self.channel.start_consuming() + + def amqpPublish(self, data, routing_key): + """ Publishes to an AMQP broker queue. """ + + self.channel.basic_publish( + exchange=self.helpers.confs_core["iotJumpWay"]["amqp"]["exchange"], routing_key=routing_key, body=data) + self.helpers.logger.info("AMQP publish complete!") + def statusCallback(self, ch, method, properties, body): """ Processes status messages. """ Thread(target=self.statusesWorker, args=(body,), daemon=True).start() @@ -106,7 +130,8 @@ def statusesWorker(self, body): }) if updateResponse: - _id = self.mongodb.insertData(self.mongodb.mongoConn.Statuses, { + + _id = self.hiashdi.insertData("Statuses", { "Use": entityType, "Location": location, "Zone": zone, @@ -117,10 +142,17 @@ def statusesWorker(self, body): "Staff": entity if entityType == "Staff" else "NA", "Status": status, "Time": datetime.now().strftime('%Y-%m-%d %H:%M:%S') - }, None) + }) + + if _id != False: + + self.helpers.logger.info( + entityType + " " + entity + " status update OK") + + else: + self.helpers.logger.error( + entityType + " " + entity + " status update KO") - self.helpers.logger.info( - entityType + " " + entity + " status update OK") else: self.helpers.logger.error( entityType + " " + entity + " status update KO") @@ -182,7 +214,8 @@ def lifeWorker(self, body): }) if updateResponse: - _id = self.mongodb.insertData(self.mongodb.mongoConn.Life, { + + _id = self.hiashdi.insertData("Life", { "Use": entityType, "Location": location, "Zone": zone, @@ -193,10 +226,18 @@ def lifeWorker(self, body): "Staff": entity if entityType == "Staff" else "NA", "Data": data, "Time": datetime.now().strftime('%Y-%m-%d %H:%M:%S') - }, None) + }) + + if _id != False: + + self.helpers.logger.info( + entityType + " " + entity + " life update OK") + + else: + + self.helpers.logger.info( + entityType + " " + entity + " life update KO") - self.helpers.logger.info( - entityType + " " + entity + " life update OK") else: self.helpers.logger.error( entityType + " " + entity + " life update KO") @@ -254,7 +295,8 @@ def sensorsWorker(self, body): }) if updateResponse: - _id = self.mongodb.insertData(self.mongodb.mongoConn.Sensors, { + + _id = self.hiashdi.insertData("Sensors", { "Use": entityType, "Location": location, "Zone": zone, @@ -269,38 +311,21 @@ def sensorsWorker(self, body): "Value": data["Value"], "Message": data["Message"], "Time": datetime.now().strftime('%Y-%m-%d %H:%M:%S') - }, None) + }) - self.helpers.logger.info( - entityType + " " + entity + " sensors update OK") - else: - self.helpers.logger.error( - entityType + " " + entity + " sensors update KO") + if _id != False: - def amqpConsumeSet(self): - """ Sets up the AMQP queue subscriptions. """ + self.helpers.logger.info( + entityType + " " + entity + " sensors update OK") - self.channel.basic_consume('Life', self.lifeCallback, - auto_ack=True) - self.channel.basic_consume('Statuses', self.statusCallback, - auto_ack=True) - self.channel.basic_consume('Sensors', self.sensorsCallback, - auto_ack=True) - self.helpers.logger.info("AMQP consume setup!") + else: - def amqpConsumeStart(self): - """ Starts consuming. """ - - self.helpers.logger.info("AMQP consume starting!") - self.channel.start_consuming() - - def amqpPublish(self, data, routing_key): - """ Publishes to an AMQP broker queue. """ + self.helpers.logger.info( + entityType + " " + entity + " sensors update KO") - self.channel.basic_publish( - exchange=self.helpers.confs_core["iotJumpWay"]["amqp"]["exchange"], routing_key=routing_key, body=data) - self.helpers.logger.info("AMQP publish complete!") - threading.Timer(300.0, self.life).start() + else: + self.helpers.logger.error( + entityType + " " + entity + " sensors update KO") def life(self): """ Sends entity statistics to HIAS """ @@ -321,11 +346,12 @@ def life(self): "Memory": str(mem), "Diskspace": str(hdd), "Temperature": str(tmp), - "Latitude": float(location[0]), - "Longitude": float(location[1]) + "Latitude": str(location[0]), + "Longitude": str(location[1]) }), "Life") self.helpers.logger.info("Agent life statistics published.") + threading.Timer(300.0, self.life).start() def respond(self, responseCode, response): """ Returns the request repsonse """ @@ -368,7 +394,7 @@ def main(): signal.signal(signal.SIGINT, Agent.signal_handler) signal.signal(signal.SIGTERM, Agent.signal_handler) - Agent.mongodbConn() + Agent.hiashdiConn() Agent.hiascdiConn() Agent.hiasbchConn() Agent.amqpConn({ diff --git a/agent_modules/helpers.py b/agent_modules/helpers.py index 18bd46c..6a95d51 100644 --- a/agent_modules/helpers.py +++ b/agent_modules/helpers.py @@ -1,8 +1,9 @@ -#!/usr/bin/env python -""" HIASCDI Global Helper Module. +#!/usr/bin/env python3 +""" HIAS AMQP IoT Agent Global Helper Module. -The HIASCDI Global Helper Module provides global helper -functions to the HIASCDI application. +The HIAS AMQP IoT Agent Global Helper Module provides +global helper functions to the HIAS AMQP IoT Agent +application. MIT License @@ -43,10 +44,11 @@ class helpers(): - """ HIASCDI Global Helper Module. + """ HIAS AMQP IoT Agent Global Helper Module. - The HIASCDI Global Helper Module provides global helper - functions to the HIASCDI application. + The HIAS AMQP IoT Agent Global Helper Module + provides global helper functions to the HIAS + AMQP IoT Agent application. """ def __init__(self, ltype, log=True): @@ -102,3 +104,9 @@ def loadConfs(self): with open(os.path.dirname(os.path.abspath(__file__)) + '/../../../../configuration/config.json') as confs: self.confs_core = json.loads(confs.read()) + + with open(os.path.dirname(os.path.abspath(__file__)) + '/../../../hiashdi/configuration/config.json') as confs: + self.confs_hiashdi = json.loads(confs.read()) + + with open(os.path.dirname(os.path.abspath(__file__)) + '/../../../hiashdi/configuration/credentials.json') as confs: + self.credentials_hiashdi = json.loads(confs.read()) diff --git a/assets/images/bug-report.png b/assets/images/bug-report.jpg similarity index 100% rename from assets/images/bug-report.png rename to assets/images/bug-report.jpg diff --git a/assets/images/feature-proposals.png b/assets/images/feature-proposals.jpg similarity index 100% rename from assets/images/feature-proposals.png rename to assets/images/feature-proposals.jpg diff --git a/assets/images/feature-request.png b/assets/images/feature-request.jpg similarity index 100% rename from assets/images/feature-request.png rename to assets/images/feature-request.jpg diff --git a/assets/images/fork.png b/assets/images/fork.jpg similarity index 100% rename from assets/images/fork.png rename to assets/images/fork.jpg diff --git a/assets/images/hias-amqp-iot-agent.xcf b/assets/images/hias-amqp-iot-agent.xcf new file mode 100644 index 0000000..50e8654 Binary files /dev/null and b/assets/images/hias-amqp-iot-agent.xcf differ diff --git a/assets/images/hias-amqp-iot-agent.jpg b/assets/images/project-banner.jpg similarity index 100% rename from assets/images/hias-amqp-iot-agent.jpg rename to assets/images/project-banner.jpg diff --git a/assets/images/repo-issues.png b/assets/images/repo-issues.jpg similarity index 100% rename from assets/images/repo-issues.png rename to assets/images/repo-issues.jpg diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..86e8b2d --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,42 @@ +# Getting Started + +![HIAS AMQP IoT Agent](img/project-banner.jpg) + +  + +# Introduction +This guide will guide you through getting started with the **HIAS AMQP IoT Agent**. + +  + +# Installation +First you need to install the required software. Below are the available installation guides. + +**PLEASE NOTE** At this point **HIAS**, **HIASBCH**, **HIASHDI** and **HIASCDI** should be **running**. + +- [Ubuntu installation guide](installation/ubuntu.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-AMQP-IoT-Agent/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to forking our repositories and submitting your pull requests. You will also find information about our code of conduct on this page. + +## 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 for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/blob/main/LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/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/img/create-hias-iotjumpway-agent.jpg b/docs/img/create-hias-iotjumpway-agent.jpg new file mode 100644 index 0000000..a2101d0 Binary files /dev/null and b/docs/img/create-hias-iotjumpway-agent.jpg differ diff --git a/docs/img/edit-hias-iotjumpway-agent.jpg b/docs/img/edit-hias-iotjumpway-agent.jpg new file mode 100644 index 0000000..6434f52 Binary files /dev/null and b/docs/img/edit-hias-iotjumpway-agent.jpg differ diff --git a/docs/img/hias-iotjumpway-agents.jpg b/docs/img/hias-iotjumpway-agents.jpg new file mode 100644 index 0000000..0fac5ed Binary files /dev/null and b/docs/img/hias-iotjumpway-agents.jpg differ diff --git a/docs/img/project-banner.jpg b/docs/img/project-banner.jpg new file mode 100644 index 0000000..f758aed 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..a7eb4f0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,34 @@ +# Documentation + +![HIAS AMQP IoT Agent](img/project-banner.jpg) + +# Welcome + +Welcome to the **HIAS AMQP IoT Agent** official documentation. This documentation includes a [getting started guide](getting-started.md) and a step by step [installation guide for Ubuntu](installation/ubuntu.md). + +The **HIAS AMQP IoT Agent** is a bridge between HIAS devices that support the AMQP protocol and the HIASCDI Context Broker. + +  + +# 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-AMQP-IoT-Agent/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to forking our repositories and submitting your pull requests. You will also find information about our code of conduct on this page. + +## 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 for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/blob/main/LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/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/ubuntu.md b/docs/installation/ubuntu.md new file mode 100644 index 0000000..f850756 --- /dev/null +++ b/docs/installation/ubuntu.md @@ -0,0 +1,163 @@ +# Ubuntu Installation + +![HIAS AMQP IoT Agent](../img/project-banner.jpg) + +# Introduction +This guide will guide you through the installation process for the HIAS AMQP IoT Agent. + +  + +# Prerequisites +You will need to ensure you have the following prerequisites installed and setup. + +## HIAS Core + +The HIAS AMQP IoT Agent is a core component of the [HIAS - Hospital Intelligent Automation Server](https://github.com/AIIAL/HIAS-Server). Before beginning this tutorial you should complete the HIAS installation guide and have your HIAS server online. + +The [HIAS Core](https://github.com/AIIAL/HIAS-Core) requires the following components to be installed, each component will be installed during the HIAS Core installation: + +### HIASBCH + +[HIASBCH](https://github.com/AIIAL/HIASBCH) (HIAS Blockchain) is a dedicated Ethereum Blockchain providing authentication & data integrity functionality to the HIAS Network. + +### HIASHDI + +[HIASHDI](https://github.com/AIIAL/HIASHDI) (HIAS Historical Data Interface) is an implementation of a REST API Server that stores HIAS network historical data and serves it to authenticated HIAS devices & applications by exposing the data through a REST API and pushing data through subscriptions. + +### HIASCDI + +[HIASCDI](https://github.com/AIIAL/HIASCDI) (HIAS Contextual Data Interface) is an implementation of a CEF Context Broker (NGSI v2). HIASCDI stores contextual data and serves it to authenticated HIAS devices & applications by exposing the data through a REST API and pushing data through subscriptions. + +  + +# Operating System +The Acute Lymphoblastic Leukemia HIAS AMQP IoT Agent supports the following operating system(s): + +- Ubuntu 18.04 + +  + +# Software +The Acute Lymphoblastic Leukemia Pytorch Segmentation 2021 Jupyter Notebook project uses the following libraries. + +- Flask +- Requests +- Web3 + +  + +# Installation +You are now ready to install the HIAS AMQP IoT Agent software. + +## Clone the repository + +Clone the [HIAS AMQP IoT Agent](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent " HIAS AMQP IoT Agent") repository from the [Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss](https://github.com/AIIAL "Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss") Github Organization. + +To clone the repository and install the project, make sure you have Git installed. Now navigate to your HIAS installation project root and then use the following command. + +``` bash + git clone https://github.com/AIIAL/HIAS-AMQP-IoT-Agent.git + mv HIAS-AMQP-IoT-Agent components/agents/AMQP +``` + +This will clone the HIAS AMQP IoT Agent repository and move the cloned repository to the agents directory in the HIAS project (components/agents/AMQP/). + +``` bash + cd components/agents/ + ls +``` + +Using the ls command in your home directory should show you the following. + +``` bash + AMQP +``` + +Navigate to the **components/agents/AMQP/** directory in your HIAS project root, 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-AMQP-IoT-Agent/blob/main/CONTRIBUTING.md "CONTRIBUTING") guide. You should pull the latest code from the development branch. + +``` bash + git clone -b "2.1.0" https://github.com/AIIAL/HIAS-AMQP-IoT-Agent.git +``` + +The **-b "2.1.0"** parameter ensures you get the code from the latest master branch. Before using the below command please check our latest master branch in the button at the top of the project README. + +## Installation script + +All other software requirements are included in **scripts/install.sh**. You can run this file on your machine from the HIAS project root in terminal. Use the following command from the HIAS project root: + +``` bash + sh components/agents/AMQP/scripts/install.sh +``` + +  + +# HIAS + +This device is a HIAS IoT Agent and uses the HIAS AMQP Broker to communicate with the HIAS network. To setup an IoT Agent on the HIAS network, head to the HIAS UI. + +The HIAS network is powered by a context broker that stores contextual data and exposes the data securely to authenticated HIAS applications and devices. + +Each HIAS IoT Agent has a JSON representation stored in the HIASCDI Context Broker that holds their contextual information. + +## HIAS IoT Agent + +A HIAS IoT Agent is a bridge between HIAS devices and applications, and the HIASCDI Context Broker. The IoT Agents process incoming data using a specific machine to machine communication protocol and then converting into a format compatible with HIASCDI, before sending the data to HIASCDI to update the contextual information. + +![HIAS IoT Agents](../img/hias-iotjumpway-agents.jpg) + +You will now need to create your HIAS IoT Agent and retrieve the agent credentials. Navigate to **IoT->Entities->Agents** and click on the **+** next to the **Network Agents** title to create a HIAS IoT Agent. + +![HIAS IoT Agent](../img/create-hias-iotjumpway-agent.jpg) + +Make sure to select **AMQP** as the protocol for your Agent. Once you have completed the form and submitted it, you can find the newly created AI Agent by navigating to **IoT->Entities->Agents** and clicking on the relevant Agent. + +On the HIAS IoT Agent page you will be able to update the contextual data for the agent, and also find the JSON representation. + +![HIAS IoT Agent](../img/edit-hias-iotjumpway-agent.jpg) + +You now need to download the credentials required to connect the Acute Lymphoblastic Leukemia oneAPI Classifier to the HIAS network. + +Click on the **Agent Credentials** section to download the credentials file. This should open your file browser, navigate to the **HIAS/components/agents/AMQP/configuration/** directory and save the file as **credentials.json**. + +  + +# Service +You will now create a service that will run your IoT Agent. Making sure you are in the HIAS project root, use the following command: + +``` bash +sh components/agents/AMQP/scripts/service.sh +``` + +  + +# Continue +Now you can continue with to the [Ubuntu usage guide](../usage/ubuntu.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-AMQP-IoT-Agent/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to forking our repositories and submitting your pull requests. You will also find information about our code of conduct on this page. + +## 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 for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/blob/main/LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/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/usage/ubuntu.md b/docs/usage/ubuntu.md new file mode 100644 index 0000000..9ad2129 --- /dev/null +++ b/docs/usage/ubuntu.md @@ -0,0 +1,52 @@ +# Ubuntu Usage + +![HIAS AMQP IoT Agent](../img/project-banner.jpg) + +# Introduction +This guide will guide you through using the **HIAS AMQP IoT Agent**. + +  + +# Start the Agent + +Now you are ready to fire up your HIAS AMQP IoT Agent, to do so use the following command: + +``` bash +sudo systemctl start HIAS-AMQP-IoT-Agent.service +``` + +The Agent will no sit listening for all data coming from the HIAS network using the AMQP protocol. Once it receives data it verifies authorization via HIASBCH and sends the data to HIASCDI & HIASHDI. + +# Manage the Agent + +To manage the agent you can use the following commands: + +``` bash +sudo systemctl restart HIAS-AMQP-IoT-Agent.service +sudo systemctl stop HIAS-AMQP-IoT-Agent.service +``` + +  + +# 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-AMQP-IoT-Agent/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to forking our repositories and submitting your pull requests. You will also find information about our code of conduct on this page. + +## 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 for versioning. + +  + +# License +This project is licensed under the **MIT License** - see the [LICENSE](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/blob/main/LICENSE "LICENSE") file for details. + +  + +# Bugs/Issues +We use the [repo issues](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](https://github.com/AIIAL/HIAS-AMQP-IoT-Agent/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..f9851c1 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,2 @@ +site_name: HIAS AMQP IoT Agent +site_url: https://www.leukemiaairesearch.com/research/project/peter-moss-medtech-research-project/hias-amqp-iot-agent