# Self-configurable Manufacturing Industrial Agents: SMIA 

[![Docker badge](https://img.shields.io/docker/pulls/ekhurtado/smia.svg)](https://hub.docker.com/r/ekhurtado/smia/) ![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/ekhurtado/SMIA?sort=semver) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e87506fff1bb4a438c20e11bb7295f51)](https://app.codacy.com/gh/ekhurtado/SMIA/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![Documentation Status](https://readthedocs.org/projects/smia/badge/?version=latest)](https://smia.readthedocs.io/en/latest/)

[![Read the Docs](https://img.shields.io/badge/readthedocs-%238CA1AF.svg?style=for-the-badge&logo=readthedocs&logoColor=white)](https://smia.readthedocs.io/en/latest/) [![PyPI](https://img.shields.io/badge/pypi-%23008bdd.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/smia/) [![DockerHub](https://img.shields.io/badge/dockerhub-%233775A9.svg?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/ekhurtado/smia) [![YouTube](https://img.shields.io/badge/YouTube-%23FF0000.svg?style=for-the-badge&logo=YouTube&logoColor=white)](https://youtube.com/playlist?list=PLs6bFF_iqW3HEwYAFOMHvW0xEngXnVF9K&si=UqWwelA3RO8C2A1u) 

[![DOIscientific](https://img.shields.io/badge/Paper-Scientific-%23fab608.svg?style=for-the-badge&logo=doi&logoColor=white)](https://doi.org/10.1016/j.jii.2025.100915) [![DOIsw](https://img.shields.io/badge/Paper-Software-%23fab608.svg?style=for-the-badge&logo=doi&logoColor=white)](https://doi.org/10.1016/j.simpa.2025.100807)

[//]: # ([![GitHub]&#40;https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white&#41;]&#40;https://github.com/ekhurtado/SMIA&#41; )

---

![I4.0 SMIA Logo Light](images/SMIA_logo_positive.png/#gh-light-mode-only "SMIA logo")
![I4.0 SMIA Logo Dark](images/SMIA_logo_negative.png/#gh-dark-mode-only "SMIA logo")

[//]: # (//Dependiendo del modo de GitHub oscuro o claro se añade una imagen u otra&#41;)

The Self-configurable Manufacturing Industrial Agents (SMIA) is a proposal for the implementation of the concept of the I4.0 Component from the Reference Architectural Model Industrie 4.0 (RAMI 4.0) as an AAS-compliant agent-based Digital Twin (DT). The features of the SMIA approach include:

- free & open-source
- AAS-compliant: standardized approach
- Ontology-based
- easily customizable and extendable
- self-configuration at software startup
- easy to start-up
- containerized solution

> [!TIP]
> For more details on Self-configurable Manufacturing Industrial Agents see the [:blue_book: **full documentation**](https://smia.readthedocs.io/en/latest/).

The development of the SMIA approach is addressed by Ekaitz Hurtado as part of a PhD thesis in the Control and Systems Integration research group at the University of the Basque Country (EHU). 

> [!IMPORTANT]
> The SMIA software is developed as part of scientific research. If you use SMIA in scientific works, please cite the following articles.
> 
> ``Scientific contribution``
> ```
> E. Hurtado, A. Burgos, A. Armentia, and O. Casquero, Self-configurable Manufacturing Industrial Agents (SMIA): a standardized approach for digitizing manufacturing assets, Journal of Industrial Information Integration, vol. 47, p. 100915, Sept. 2025, doi: 10.1016/j.jii.2025.100915
> ```
> ``Software contribution``
> ```
> E. Hurtado, I. Sarachaga, A. Armentia, and O. Casquero, An open-source reference framework for the implementation of type 3 Asset Administration Shells, Software Impacts, vol. 27, p. 100807, Apr. 2026, doi: 10.1016/j.simpa.2025.100807
> ```

## Project structure

The repository of the SMIA project is structured as follows:

- [additional_resources](https://github.com/ekhurtado/SMIA/tree/main/additional_resources): additional resources developed and offered related to the SMIA approach.
  - [aas_ontology_reader](https://github.com/ekhurtado/SMIA/tree/main/additional_resources/aas_ontology_reader): this resource contains the source code of a reader capable of analyzing an AAS model based on a given OWL ontology.
  - [aasx_package_explorer_resources](https://github.com/ekhurtado/SMIA/tree/main/additional_resources/aasx_package_explorer_resources): this resource contains the JSON files to extend the AASX Package Explorer software with the Capability-Skill-Service (CSS) model.
  - [css_smia_ontology](https://github.com/ekhurtado/SMIA/tree/main/additional_resources/css_smia_ontology): this resource contains the ontology for the Capability-Skill-Service (CSS) model in an OWL file. It also provides some ExtendedClasses implemented in Python.
  - [gui_agent](https://github.com/ekhurtado/SMIA/tree/main/additional_resources/gui_agent): this resource provides a SPADE agent with an easy-to-use graphical interface. This agent provides several useful functionalities for SMIA usage and execution.
- [additional_tools](https://github.com/ekhurtado/SMIA/tree/main/additional_tools): additional tools developed to support the SMIA approach or to obtain extended SMIA agents with additional logic.
  - Extended agents
    - [smia_pe](https://github.com/ekhurtado/SMIA/tree/main/additional_tools/extended_agents/smia_pe): SMIA Production Execution (PE) is an extended agent with autonomy for interpret and autonomously execute BPMN workflows.
    - [smia_hi](https://github.com/ekhurtado/SMIA/tree/main/additional_tools/extended_agents/smia_hi): SMIA Human Interface (HI) is an extended agent with a GUI to manage incoming CSS-related requests to represent a human as a manufacturing asset.
    - [smia_operator_agent](https://github.com/ekhurtado/SMIA/tree/main/additional_tools/extended_agents/smia_operator_agent): SMIA Operator is an extended agent with a GUI that allows you to perform CSS-related requests with an easy-to-use interface.
  - Infrastructure components
    - [smia_i_kb](https://github.com/ekhurtado/SMIA/tree/main/additional_tools/infrastructure_components/smia_i_kb): SMIA-I Knowledge Base (KB) is an ontological database to support SMIA ecosystem offering management of CSS-related information as well as agent-related information (e.g., registration of instances).
    - [smia_ism](https://github.com/ekhurtado/SMIA/tree/main/additional_tools/infrastructure_components/smia_ism): SMIA Infrastructure Services Manager (ISM) is an extended agent that to acts as a mediator, encapsulating essential non-agent infrastructure services and exposing them to the normalized SMIA-based MAS.
  - [camunda_smia_plugin](https://github.com/ekhurtado/SMIA/tree/main/additional_tools/camunda_smia_plugin): this tool is a plugin for Camunda Modeler software that is able to query functional information from the SMIA-I KB and offer it to the user. It also provides extended BPMN elements to ease the development of valid CSS-driven workflows for SMIA PE. 
- [examples](https://github.com/ekhurtado/SMIA/tree/main/examples): some examples to facilitate the use of the solution.
  - [docker_compose_deployment](https://github.com/ekhurtado/SMIA/tree/main/examples/docker_compose_deployment): required files to easily deploy SMIA using the Docker Compose tool.
  - [smia_extended](https://github.com/ekhurtado/SMIA/tree/main/examples/smia_extended): an example of files related to a SMIA extension case.
  - [tutorials](https://github.com/ekhurtado/SMIA/tree/main/examples/tutorials): all the resources shown in the SMIA tutorials.
- [src](https://github.com/ekhurtado/SMIA/tree/main/src): the entire source code of the SMIA software.
  - [smia](https://github.com/ekhurtado/SMIA/tree/main/src/smia): the main Python package for the entire source code of the SMIA.

## Usage

> [!IMPORTANT]
> The project is currently under active development, 
> so new features and bug fixes will be introduced continuously.
> Therefore, although SMIA is not yet an industry-ready implementation,
> validations of the approach with different use cases will be conducted during its development.
 
Multiple ways of running SMIA software are available. 

### Download source code

The source code inside the ``src`` folder can be downloaded, and there are two launchers to run the software easily. If the folder where the launchers are located is accessed, it is possible to run SMIA using the following command:

```bash
python3 smia_cli_starter.py --model "<path to AASX package>"
```

> [!TIP]
> The launcher ``smia_starter.py`` specifies the AAS model manually, so the code must be modified. Just change the line that specifies the path to the AASX package that contains the AAS model. Then it can be executed:
>```bash
>python3 smia_starter.py
>```

### Install as pip package

The SMIA approach is also available as Python package in PyPI. It can be easily installed using [pip](https://pip.pypa.io/en/stable/):

```bash
pip install smia
```

> [!NOTE]
> The PyPI project is available at <https://pypi.org/project/smia/>.

The PyPI SMIA package contains all the source code and there are determined the necessary dependencies, so they can be automatically installed by pip, so it can run SMIA directly by:

```bash
python3 -m smia.launchers.smia_cli_starter --model "<path to AASX package>"
```

[//]: # (TODO actualizar con el nombre cuando se publique)

### Run as Docker container

The SMIA approach is also available as Docker image in DockerHub. To run SMIA software the AAS model should be passed as environmental variable:

```bash
docker run -e model=<path to AASX package> gcis-upv-ehu/smia:latest-alpine
```
[//]: # (TODO actualizar con el nombre cuando se publique)

> [!NOTE]
> The SMIA Docker Hub repository is available at <https://hub.docker.com/r/ekhurtado/smia>.

## Discussions

> [!NOTE]
> [Discussions](https://github.com/ekhurtado/SMIA/discussions) page has been set as available to share announcements, create conversations, answer questions, and more.

## Dependencies

The SMIA software, as it has been built following an Open Source Software Engineering approach, integrates some mature Python packages.

| Package name                                                   | Version | License             | Has it been modified |
|----------------------------------------------------------------|---------|---------------------|----------------------|
| [spade](https://pypi.org/project/spade/)                       | 4.0.3   | MIT                 | No                   |
| [basyx-python-sdk](https://pypi.org/project/basyx-python-sdk/) | 1.2.1   | MIT                 | No                   |
| [owlready2](https://pypi.org/project/owlready2/)               | 0.48    | GNU LGPL licence v3 | No                   |

## License

GNU General Public License v3.0. See `LICENSE` for more information.
