Quickstart

Quickstart

Once you have installed the framework and created your first project, you're ready to go. Start the blank example in your connector-starter project to make sure everything went according to plan using:

$ poetry run connector start

This should start the connector server. This server has only the compulsory SiLAService feature and a small example feature, the GreetingProvider, registered. For local, temporary development, you can create a features folder within your project tree and start composing your first SiLA Feature.

In the connector-starter project, go to the folder that contains the example feature: In there, you can see two files:

├── connector
  ├── feature
    ├── examples
      ├── __init__.py
      ├── greeting_provider_base.py

The greeting_provider_base.py file contains the abstract base class of our feature. This where the feature definition is done. You can create more features in the example namespace simply by adding more files and defining the abstract base class in them. Make sure to add the class to the __init__.py file, so you can more easily import it in your implementation file.

We will not go into feature definition in during this quickstart. You can directly learn about it in the concepts section or work through the tutorial to build one step by step.

Once your connector is up and running, you can move it to your connector repo and push it to a feature branch and formulate a pull request. We will review for best practice and standard compliance and add it to the CDK for everyone else to use. We will also take care of syncing the connector CDK feature collection with the official SiLA Base repository.

The implementation is decoupled from the feature definition. For a specific SiLA Connector implementation, you have to create an implementation file. In this example case you can find the greeting_provider.py file here:

├── connector
  ├── feature
  ├── __init__.py
  ├── __main__.py
  ├── greeting_provider.py

In there, we import the greeting provider base class and initialize it using the super.__init__() function. You can also declare some class attributes that you may need later on for the implementation of the commands and properties.

from .features.examples.greeting_provider import GreetingProviderBase


class GreetingProvider(GreetingProviderBase):

    def __init__(self):
        super().__init__()
        self.__start_year = datetime.datetime.now().year

Within this class, every function defined in the base class must be implemented. The base class contains a say_hello command and a start_year property. They are added to our feature implementation. Within these, you can do your implementation!

    async def say_hello(
        self, name: str
    ) -> str:
        return f"Hello SiLA 2 {name}"

    async def start_year(self):
        return self.__start_year

After implementation, the feature must be added to the server in the __init__.py file in the connector folder in which also the server properties can be defined.

├── connector
  ├── feature
  ├── __init__.py
  ├── __main__.py
  ├── greeting_provider.py

Update the server name, type, description, version, and vendor_url. Use the register function to add the new feature to the server.

async def create_app():
    app = Connector(
        {
            "sila_server": {
                "name": "UniteLabs Example",
                "type": "Example",
                "description": "A UniteLabs SiLA Python Example Server",
                "version": "0.1.0",
                "vendor_url": "https://unitelabs.io/",
            }
        })
    app.register(GreetingProvider())
    return app

Done! Run poetry run connector start to start!

CLOUD_SERVER_ENDPOINT__ENDPOINT = <endpoint-adress>:<endpoint-port>
CLOUD_SERVER_ENDPOINT__SECURE = True
SILA_SERVER__UUID = 38f55c97-65ab-4abf-8b1d-f5e65a645331
SILA_SERVER__HOST = 0.0.0.0
SILA_SERVER__PORT = 50001