Develop your own module!

Get started with our documentation guide and example code

  • Getting started

  • Handling installation

  • Test your module

  • Build your module

  • Update your module

  • Add Telegram commands

    Getting Started

    You always wanted to develop your own Hobbit module? You're in luck, because now it's easier than ever!

    Project Hobbit runs using a Django v. 1.11 application, and every module is its own small Django app, so you might want to check out a basic Django guide before you get started!

    When you're ready to get started, pull the Project Hobbit code and copy the folder ModuleManager/ModuleManager/dummy and paste it on the same path level. Rename the folder to the id of the your module! Please note the id should only contain letters, numbers, dashes and underscores. Using the find and replace function in your editor of choice, search and replace the word "dummy" with the id of your module. All folders which are named "dummy" should also be renamed.

    And you're ready to get programming! Spend some time going through the example module - we have provided some comments to help you understand how everything works.


    Here are some important files and folders to keep an eye out for:


    • dummy/models.py

      Here is where your data models are defined. You can define data which is specific to each user or data which is uniform for all users.

    • dummy/forms.py

      If the user needs to use a form to enter any changes to their data, this is where they should be implemented.

    • dummy/models.py

      Here is where your data models are defined. You can define data which is specific to each user or data which is uniform for all users.

    • dummy/migrations

      Find out what migrations are here. You shouldn't need to make any changes here manually, but after you change your models, you might need to run "python manage.py makemigrations".

    • dummy/views.py

      Here you can define what views your module has, which html templates are served with which views, and which data you deliver to your views. Please note detail, miniature and settings views are compulsory.

    • dummy/templates/dummy/

      Here are all the html files for your module. Don't delete the detail.html, miniature.html, settings.html files! Please note the miniature template is served on the dashboard as a non-clickable iframe, so please don't include any buttons in your miniature view!

    • dummy/urls.py

      This is where you define the urls in your module and link them to your views.

    • dummy/static/dummy/

      This is where all the static files you need live - images, css files, js files and whatever else your module might require.

    • dummy/__init__.py

      Any code that should be executed every time the Project Hobbit app starts belongs here.

    • dummy/install.sh, dummy/install.py

      These files are installation scripts. Please continue to the next section to find out more.

    • dummy/python_packages.txt, dummy/dep.txt

      These files handle dependencies. Please continue to the next section to find out more.

    Handling Installation

    Linux dependencies

    Does your module have special Linux dependencies, which need to be installed on the ODROID-C2? Then please list these in the file dummy/dep.txt. Each package name should be written on a new line. When your module is installed, these packages will be fetched from the apt repository and installed. Please be sure, that these packages exist for our image - a minimal Ubuntu image for the ODROID-C2. Don't forget, if you're testing installation of your module while running the Project Hobbit app locally on another OS, the installation of these dependencies might fail!

    Python dependencies

    Does your module have special python dependencies? Please list these in the file dummy/python_packages.txt. Each module name should be written on a new line. When your module is installed, these modules will be automatically installed using the "pip install" command.

    Linux install script

    Do you need a more manual installation, or want to install from a different source? You can write a custom shell script. You need to create the file dummy/install.sh. This shell script will be executed on installation.

    Python install script

    You are not comfortable with shell scripts or want to do some more python setup? Create a file dummy/install.py. Just like the shell script it will be executed on installation.

    Test your module

    In order to run the Project Hobbit application locally, please follow the instructions in the readme.md. Once you're running the app, please head over to the installation page at /installation. Please remove any other source urls - this might cause unnecessary complications. Add a new source dev:your_module_id. Now you should be able to test out your module!

    Build your module

    Prerequisites

    Your own server where you can host your module!

    Ready to show the world your module?

    Ok, let's do it! Compress the contents of your module folder (not the folder itself!) as a .zip file. Name the zip with the id of your module. Create a module_list.json and list your module as in the example below:

                            
        {
           "last_updated":"2017-11-23",
           "base_url": "http://my-server.com/modules",
           "extension": ".zip",
    
           "modules": [
            {
                "name": "dummy",
                "version": 1,
                "date": "2018-01-04",
                "author": "Roman",
                "description": "Template",
                "thumbnail": ""
            }
           ]
        }
                            
                          

    Change the last_update and the date fields to the date today. Replace http://my-server.com/ with the url to where you intend to host the module on your server.

    Host the files on your server in the following folder structure:
    /module_list.json
    /modules/dummy.zip

    Now you can use http://my-server.com/module_list.json as a source when installing modules!

    Would you like your module to be included in the official Project Hobbit module source? Please contact us to submit your module for the code review process to become an authorised Project Hobbit module. During code review we will check for any security vulnerabilities before we recommend your module to our user base.

    Update your module

    Users can install updates for their installed modules. However this is only possible if you change your module_list.json each time you change or improve your module.

    Once you have replaced your module_id.zip on your server with the new version, please update the last_updated field in the module_list.json. In addition, please update the date field and raise the version number for your module.

    Add Telegram commands

    Add commands for your module to the Hobbit Telegram Bot! Users can message these commands using Telegram to the Bot in order to execute code in your module or receive data in a response message.

    Project Hobbit uses the python wrapper for the Telegram API. Check out the file telegram_commands.py in the dummy module for an example of how you can create your very own Telegram commands for the Hobbit Telegram Bot.