Creating your first cog

Examples

We have a cog template you can use to get started with cog development. You can get the template here

We also have a helper tool which can generate a template project for you called tcli. To create a new project, use tcli init to create a cog in current directory or tcli init [DIRECTORY] to create the cog in the specified directory.

The file structure

The file structure is important when creating a cog. All the python code for a cog goes in the src folder. The config files (name.hooks and name.cog) go into the root directory.

test-cog/
|-- src
|   `-- hello.py
|-- test.cog
`-- test.hooks

IDE/Editor setup

The only supported editors are VS Code and forks of VS Code like Codium. You can choose to use whichever editor you like, however, there is an extension built to help with testing called 'Asgard Cogs'. As of the latest version (0.0.4), it is only compatible with MacOS and Linux, so for Windows users, we recommend setting it up inside of WSL. More info here. You can get the extension on VSCode Marketplace

The files

Each cog has 2 main config files. One is a .cog file and the other is a .hooks file. These make up the standard cog structure required by the TCore to detect them.

Assuming name as a placeholder for the name of the cog. Both files follow a YAML format.

1. name.cog : This file has only 2 fields
   • name: Name of the cog. This has to match the name of the .cog and .hooks file.
   • namespace: Same as name for now, but it is to going to be used for dependency resolving.
2. name.hooks : This file has 2 main fields with various sub-fields
   • hooks :
     • namespace: same as the Namespace in the .cog file.
     • source_path: By default, this has to be src/. It points to ./src/* where all the python files are stored.
     • depends: WIP but informs on which cogs are required for this cog to function.
     • actions: The action set this cog has. This has to correspond with the name of the .py file in the source path.
   • config: Gets loaded into System.SafeConfig which can be referenced from inside the cog.

Coding your cog

There is a utility tool for creating cogs called tcli. It is helpful to have this tool, but if you do not want to install it, you can create a project from this template.

Start by creating a file called hello.py in the src folder. This will represent an entry point. While most of the code is in python, there is one significant change to it. We have a return statement at the end of every file, outside a function. This is because the cog file represents the body of a function. We will be creating a cog which returns "Hello World" with the time stamp of when the request was made.

Now edit the .hooks file to point to our newly created file (hello.py). Edit the actions field to have

actions:  hello: "hello" # the name should be the same

Now let's edit the file

# src/main.py""" Entire file is an entry point """from datetime import datetimenow = datetime.now()current_time = now.strftime("%H:%M:%S")# This can be any return typereturn f"Hello World! This message was sent at {current_time}"

def hello():  from datetime import datetime  now = datetime.now()  current_time = now.strftime("%H:%M:%S")  # Answer = Exponential    return f"Hello World! This message was sent at {current_time}"

Packaging a cog

Once you are done writing the cog, you can zip the whole folder. It is recommended to change the extension of the folder to .cog from .zip, as it makes it easier to recognise if a file is an archive or a cog. You can then load this cog using the TCore app on your phone and that should be it! You can check if the cog works by sending a POST request to asgard, which is hosted on your phone running TCore.

POST: http://<url provided by the TCore app>:8080/asgardBODY:{  "hook":"test-cog",  "action": "hello", // Actions == function in mobile  "function":"hello",  "params": []}RESPONSE:{  "code": 200,  "data": {    "msg": "Hello World! This message was sent at 00:00:00" // success, otherwise we get an Exception  }}