From 0f4aaa8d77f7c2afb3f2f4346012ee06fd52e03e Mon Sep 17 00:00:00 2001 From: Alexar Date: Sat, 25 Oct 2025 21:54:42 +1100 Subject: [PATCH] Fixes 50 improves Quick Start documentation --- ReadMe.md | 92 +++++++++++++++++-- .../examples/aloha_honua/ReadMe.md | 90 ++++++++++-------- 2 files changed, 136 insertions(+), 46 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index 5779cee..1a0c951 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -28,14 +28,14 @@ See [**Wiki**](https://github.com/geekscape/aiko_services/wiki) for [Glossary (c Recommended when simply trying Aiko Services by using existing examples and tools. Installs the [Aiko Services package from PyPI](https://pypi.org/project/aiko_services) -``` +```python pip install aiko_services ``` ## Installing from GitHub Recommended when using Aiko Services as a framework for development -``` +```bash git clone https://github.com/geekscape/aiko_services.git cd aiko_services python3 -m venv venv # Once only @@ -48,7 +48,7 @@ pip install -e . # Install Aiko Services for development Recommended when making an [Aiko Services release to PyPI](https://pypi.org/project/aiko_services) After **installing from GitHub** *(above)*, perform these additional commands -``` +```bash pip install -U hatch # Install latest Hatch build and package manager hatch shell # Run shell using Hatch to manage dependencies # hatch test # Run local tests (to be completed) @@ -57,21 +57,95 @@ hatch build # Publish Aiko Services package to PyPI # Quick start -After **installing from GitHub** *(above)*, choose whether to use a public MQTT server ... or to install and run your own MQTT server +Here, we assume a clean Uubuntu system. We will install MQTT Server and then start Aiko Services to use the local MQTT server. -It is easier to start by using a public remotely hosted MQTT server to tryout a few examples. -For the longer term, it is better and more secure to install and run your own MQTT server. +1. Install MQTT Server: +```bash +sudo apt update +sudo apt install mosquitto mosquitto-clients +``` -## Running your own mosquitto (MQTT) server +2. Run the MQTT Server: +Open a terminal dedicated to MQTT and start it manually: +```bash +mosquitto +``` -- Install the mosquitto (MQTT) server on [Linux](https://docs.vultr.com/install-mosquitto-mqtt-broker-on-ubuntu-20-04-server), [Mac OS X](https://subscription.packtpub.com/book/iot-and-hardware/9781787287815/1/ch01lvl1sec12/installing-a-mosquitto-broker-on-macos) or [Windows](https://cedalo.com/blog/how-to-install-mosquitto-mqtt-broker-on-windows) +3. Install Aiko Services: +```bash +git clone https://github.com/geekscape/aiko_services.git +cd aiko_services +python3 -m venv venv # Once only +source venv/bin/activate # Each terminal session +pip install -U pip # Install latest pip +pip install -e . # Install Aiko Services for development +``` + +4. Run Aiko Services: +Open a terminal dedicated to Aiko Dashboard: +```bash +cd aiko_services +source venv/bin/activate +./scripts/system_start.sh +``` + +5. Run the Aloha Honua example: +In a seperate terminal, run the example that is provided in the repository. +```bash +cd aiko_services +source venv/bin/activate +./src/aiko_services/examples/aloha_honua/aloha_honua_0.py +``` + +# Using a mosquitto (MQTT) Server + +After **installing from GitHub** *(above)* you have two choices. Using a public MQTT server or host one yourself. + +In the long run it is better and more secure to install and serve MQTT yourself. + +1. Using a public MQTT server + +An example of a public MQTT Server: +``` +Broker Address： broker.emqx.io +TCP Port： 1883 +WebSocket Port： 8083 +``` +Read more on [emqx website](https://www.emqx.com/en/blog/the-easiest-guide-to-getting-started-with-mqtt). + +If you choose to use a public MQTT Server, you need to specify it as an envirnment variable: `AIKO_MQTT_HOST`. + +Example: +```bash +export AIKO_MQTT_HOST="broker.emqx.io" +./scripts/system_start.sh + +# OR + +AIKO_MQTT_HOST="broker.emqx.io" ./scripts/system_start.sh +``` + +2. Install and host your own MQTT Server: + +In Ubuntu: +```bash +sudo apt update +sudo apt install mosquitto mosquitto-clients +``` +Check out documentatin for [Linux](https://docs.vultr.com/install-mosquitto-mqtt-broker-on-ubuntu-20-04-server), [Mac OS X](https://subscription.packtpub.com/book/iot-and-hardware/9781787287815/1/ch01lvl1sec12/installing-a-mosquitto-broker-on-macos) or [Windows](https://cedalo.com/blog/how-to-install-mosquitto-mqtt-broker-on-windows). -On Linux or Mac OS X: Start mosquitto, aiko_registrar and aiko_dashboard +Now, before starting the Aiko Services, you'll need to ensure that MQTT server is running: +```bash +# Manually start mosquitto +mosquitto ``` +Now, in a seperate terminal, you can start Aiko Services: +```bash ./scripts/system_start.sh # default AIKO_MQTT_HOST=localhost ``` # Examples +You can find a set of examples under `src/aiko_services/examples`. - [Aloha Honua examples](src/aiko_services/examples/aloha_honua/ReadMe.md) (hello world) diff --git a/src/aiko_services/examples/aloha_honua/ReadMe.md b/src/aiko_services/examples/aloha_honua/ReadMe.md index 7d96413..2fe83b3 100644 --- a/src/aiko_services/examples/aloha_honua/ReadMe.md +++ b/src/aiko_services/examples/aloha_honua/ReadMe.md @@ -26,35 +26,41 @@ The AlohaHonua [Actor](https://en.wikipedia.org/wiki/Actor_model) below is a dis *Source code: [aloha\_honua\_0.py](aloha_honua_0.py)* - from aiko_services.main import * +```python +# file: aloha_honua_0.py - class AlohaHonua(Actor): - def __init__(self, context): - context.call_init(self, "Actor", context) - print(f"MQTT topic: {self.topic_in}") +from aiko_services.main import * - def aloha(self, name): - self.logger.info(f"AlohaHonua {name} !") +class AlohaHonua(Actor): + def __init__(self, context): + context.call_init(self, "Actor", context) + print(f"MQTT topic: {self.topic_in}") - if __name__ == "__main__": - init_args = actor_args("aloha_honua") - aloha_honua = compose_instance(AlohaHonua, init_args) - aiko.process.run() + def aloha(self, name): + self.logger.info(f"AlohaHonua {name} !") + +if __name__ == "__main__": + init_args = actor_args("aloha_honua") + aloha_honua = compose_instance(AlohaHonua, init_args) + aiko.process.run() +``` [### Running the AlohaHonua Actor with a local MQTT server](#run-local-server) After the Aiko Services framework has been installed, you'll need to start the Core Services, which are the [mosquitto](https://mosquitto.org) ([MQTT server](https://en.wikipedia.org/wiki/MQTT#MQTT_broker)) and the Aiko Registrar on your computer. The Aiko Dashboard will also be started, which provides interactive monitoring and control. - # Current working directory should be the top-level of the Aiko Services repository - # The first command starts mosquitto, Aiko Registrar and Aiko Dashboard - ./scripts/system_start.sh - Starting: /usr/sbin/mosquitto - Starting: aiko_registrar +```bash +# Current working directory should be the top-level of the Aiko Services repository +# The first command starts mosquitto, Aiko Registrar and Aiko Dashboard +./scripts/system_start.sh + Starting: /usr/sbin/mosquitto + Starting: aiko_registrar - # Use another terminal session, also starting at the top-level of the repository - cd examples/aloha_honua - ./aloha_honua_0.py - MQTT topic: aiko/nomad.local/123/1/in +# Use another terminal session, also starting at the top-level of the repository +cd examples/aloha_honua +./aloha_honua_0.py + MQTT topic: aiko/nomad.local/123/1/in +``` Whilst the AlohaHonua Actor is running, the Aiko Dashboard will show a list of the available Services / Actors and selecting `aloha_honua` will show further details ... @@ -73,14 +79,16 @@ Whilst the AlohaHonua Actor is running, the Aiko Dashboard will show a list of t The AlohaHonua Actor example, Core Services and Aiko Dashboard can be stopped, as follows ... - # Type Control-C to stop the ./aloha_honua_0.py program +```bash +# Type Control-C to stop the ./aloha_honua_0.py program - # Select the terminal session running the Aiko Dashboard and press the "x" key +# Select the terminal session running the Aiko Dashboard and press the "x" key - # Then stop the Core Services - ../../scripts/system_stop.sh - Stopping: aiko_registrar - Stopping: /usr/sbin/mosquitto +# Then stop the Core Services +../../scripts/system_stop.sh + Stopping: aiko_registrar + Stopping: /usr/sbin/mosquitto +``` ### Examining the AlohaHonua Actor source code @@ -88,14 +96,18 @@ The AlohaHonua Actor example, Core Services and Aiko Dashboard can be stopped, a Start by importing the Aiko Services [module](https://www.w3schools.com/python/python_modules.asp) for the AlohaHonua Actor. - from aiko_services.main import * +```python +from aiko_services.main import * +``` The AlohaHonua class is defined as a Python class that inherits from the Aiko Services' Actor class. The class constructor method `__init__()` is required, but don't worry about its implementation for the moment. The `print()` statement shows the automagically generated MQTT topic path for communicating with this Actor instance and a target for publishing MQTT messages. - class AlohaHonua(Actor): - def __init__(self, context): - context.call_init(self, "Actor", context) - print(f"MQTT topic: {self.topic_in}") +```python +class AlohaHonua(Actor): + def __init__(self, context): + context.call_init(self, "Actor", context) + print(f"MQTT topic: {self.topic_in}") +``` One of the features that the Actor `__init__()` function provides is a [logger](https://en.wikipedia.org/wiki/Logging_(computing)) [instance](https://en.wikipedia.org/wiki/Instance_(computer_science)#Object-oriented_programming) for this Actor @@ -112,17 +124,21 @@ By default, the `_LOGGER` instance will use distributed logging (via MQTT) that Actors can define functions that can be invoked directly by other Actors (via MQTT messages). - def aloha(self, name): - self.logger.info(f"AlohaHonua {name} !") +```python +def aloha(self, name): + self.logger.info(f"AlohaHonua {name} !") +``` When coding in Python, Aiko Actors can be discovered and their functions invoked via a regular Python function call. For testing and diagnosis, MQTT CLI tools can also used to *publish* hand-crafted messages and *subscribe* to observe the output from one or more Actors. The standard Python `__main__` code defines the AlohaHonua class constructor method` __init__()` arguments, e.g the Actor `name`. Then creates (*composes*) the AlohaHonua Actor instance. Finally, the Aiko Process main event loop can be run (which is a blocking call). - if __name__ == "__main__": - init_args = actor_args(ACTOR_NAME) - aloha_honua = compose_instance(AlohaHonua, init_args) - aiko.process.run() +```python +if __name__ == "__main__": + init_args = actor_args(ACTOR_NAME) + aloha_honua = compose_instance(AlohaHonua, init_args) + aiko.process.run() +``` The Aiko Services framework uses the [Inversion of Control (IoC)](https://en.wikipedia.org/wiki/Inversion_of_control) design pattern, which enables an extensible, event-driven programming model.