Skip to content

Fixes #50 improves Quick Start documentation #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pendashteh wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fixes #50 improves Quick Start documentation #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 83 additions & 9 deletions ReadMe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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)
Expand Down
90 changes: 53 additions & 37 deletions src/aiko_services/examples/aloha_honua/ReadMe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ...

Expand All @@ -73,29 +79,35 @@ 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

*Source code: [aloha\_honua\_0.py](aloha_honua_0.py)*

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

Expand All @@ -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.

Expand Down