mirror of
https://github.com/PiBrewing/craftbeerpi4.git
synced 2024-09-19 22:07:28 +02:00
115 lines
No EOL
3.1 KiB
ReStructuredText
115 lines
No EOL
3.1 KiB
ReStructuredText
Standard & Guidelines
|
|
=====================
|
|
|
|
Python
|
|
^^^^^^
|
|
|
|
CraftBeerPi 4.x is based on Pyhton 3.7x.
|
|
As a main framework CraftBeerPi is based on `aiohttp`
|
|
|
|
* aioHTTP https://aiohttp.readthedocs.io/en/stable/
|
|
|
|
CBPiEventBus
|
|
------------
|
|
|
|
One core concept of CraftBeerPi 4.x is the CBPiEventBus.
|
|
It should be avoided to call method on a controller directly. Events should be fired and listener methods should be used.
|
|
This makes sure that all components are loosely coupled. New plugins can listen on events and extend or change the functionality easily.
|
|
|
|
Here an example how to fire an event
|
|
|
|
.. code-block:: python
|
|
|
|
cbpi.bus.fire(topic="notification/hello", key="hello", message="Hello World")
|
|
|
|
|
|
Here an example how listen on an event.
|
|
|
|
.. code-block:: python
|
|
|
|
@on_event(topic="actor/+/switch/on")
|
|
def listener(self, id , power=100, **kwargs) -> None:
|
|
pass
|
|
|
|
|
|
.. note::
|
|
|
|
It is important to add **kwargs as parameter to the listening method. This makes sure that maybe addtional event paramenter are not causing an exception.
|
|
|
|
|
|
A list of all registered events listeners can be found under: `http://<IP_ADDRESS>:<PORT>/system/events`
|
|
|
|
|
|
HTTP Endpoints
|
|
--------------
|
|
|
|
A new HTTP endpoints should be exposed by adding the `@request_mapping` decorator on top of an async method.
|
|
The `path` parameter defines the URL path. The `auth_required` defines whether the endpoint should be accessible public or within a user session only.
|
|
Typically you perform just some basing parameter validation and fire an event so that other components and controllers can perform some actions.
|
|
|
|
.. code-block:: python
|
|
|
|
@request_mapping(path="/{id:\d+}/on", auth_required=False)
|
|
async def http_on(self, request) -> web.Response:
|
|
self.cbpi.bus.fire(topic="actor/%s/switch/on" % id, id=id, power=99)
|
|
return web.Response(status=204)
|
|
|
|
.. note::
|
|
|
|
The Events are process in an async way. Results will be pushed to the client via CBPiWebSocket Event.
|
|
|
|
|
|
CBPiWebSocket
|
|
-------------
|
|
|
|
The CBPiWebSocket is listening on `http://<IP_ADDRESS>:<PORT>/ws`
|
|
All events are forwarded to all connected web socket clients.
|
|
|
|
The CBPiWebSocket Event is having the following structure.
|
|
|
|
* topic -> is the bus topic
|
|
* data -> the event data
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"topic":"notification/step",
|
|
"data":{
|
|
"key":"step",
|
|
"message":"Hello World",
|
|
"type":"info"
|
|
}
|
|
}
|
|
|
|
|
|
|
|
SQL Files
|
|
---------
|
|
Currently only one SQL file for database initialisation is available.
|
|
It's located under: `./core/sql`
|
|
|
|
|
|
|
|
Web User Interface
|
|
^^^^^^^^^^^^^^^^^^
|
|
The Web UI is based on ReactJS + Redux.
|
|
The build process is based on webpack and bable.
|
|
|
|
* ReactJS: https://reactjs.org/
|
|
* Redux: https://redux.js.org/
|
|
* WebPack: https://webpack.js.org/
|
|
* Babel: https://babeljs.io
|
|
|
|
REST API
|
|
^^^^^^^^
|
|
The REST API of CraftBeerPi is documented using Swagger.io
|
|
After server startup you can find the API documentaiton under: `http://<IP_ADDRESS>:<PORT>/api/doc`
|
|
|
|
To generate the swagger file `aiohttp-swagger` is used. for more information see: https://aiohttp-swagger.readthedocs.io/en/latest/
|
|
|
|
|
|
|
|
Custom Extensions & Pluins
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Custom Extension should be placed under `./core/extensions` |