Note: This guide is fairly complex and has many steps. If you're new to PiBakery, programming, Raspberry Pi or Git, you might experience some difficulty. Please feel free to tweet @PiBakery or email david@pibakery.org with any questions you may have.

Why contribute your own blocks?

There are a few reasons why you might want to add your own custom blocks into PiBakery.

The first would be because you have a setup script that you always run on your Raspberry Pi, that you would like to have a PiBakery block for, and you would also want others to be able to use your script. An example of this would be a block that edits the configuration of Apache to a certain output. You might always run this on your Raspberry Pi, and think that others might want to do the same, and therefore having it as a block in PiBakery would be a useful addition.

The second reason would be if you are the developer or manufacturer (or even just a user!) of a piece of software or hardware for Raspberry Pi, and you would like others to be able to easily install that software or enable that hardware with a single PiBakery block. For example, if you had written a new GPIO program for Raspberry Pi, creating a PiBakery block for it would allow anyone to easily install it with the drag and drop interface, and without fiddling around with the command line.

Understanding PiBakery Blocks

Before you can create and submit blocks to PiBakery, you'll need to understand how PiBakery blocks work.

Each block has a minimum of two files: a JSON file which describes how the block looks and acts to PiBakery, and a script file which contains the action of the block. The script block can be in any language of your choosing - Python, Bash, etc.

For blocks that have inputs (fields, menus) these values are passed to your script as command line arguments. You should be able to find information about how to retrieve values from command line arguments for the language you have chosen online.

If you're going to be creating and submitting a block, it's best if you try and make your block work offline, rather than just when the Pi is online. Rather than downloading and then running a script, it would be best if you included that script with your block, so it'll work offline too.

1. Create folder and files

First, you'll need to decide on the name of your block. This name is only every shown to users when that block is being run on their Raspberry Pi, should contain no spaces, and be no longer than 20 characters.

Create a folder of this name, and inside it create a file called <blockname>.json. For example, if I wanted to add a block called foobar, I would create a folder called foobar and inside that folder I would create a file called foobar.json

2. Edit <blockname>.json file

Now you need to edit the <blockname>.json file. This is the file that contains all the information about the block - what it looks like, what category it goes into, what inputs it has, the script it should run, etc.

An example JSON file can be seen below:

{
	"name": "exampleblock",
	"text": "Example Block\\nNewline\\nText Input %1\\nText Input 2 %2\\nNumber Input %3\\nMenu Input %4",
	"script": "examplescript.py",
	"network": true,
	"continue": true,
	"type": "setting",
	"category": "setting",
	"shortDescription":"A few words to describe what this block is",
	"longDescription":"A longer description to describe this block, with information on what the block does, what the inputs in the block are for, and what types they should be. Also whether the block requires a network connection.",
	"args": [
		{
			"type": "text",
			"default": "sample text",
			"maxLength":0
		},
		{
			"type": "text",
			"default": "17 characters max",
			"maxLength":17
		},
		{
			"type": "number",
			"default": "8080",
			"maxLength":4
		},
		{
			"type": "menu",
			"options": ["Option 1", "Option 2", "Option 3"]
		}
	]
}

Below is a description of each of the properties in the JSON file:

• name
  String
  Required
  This should be the same name that you used for the folder and json file name

• text
  String
  Required
  The text display of the block. For a newline in the block, use \\n. To add an input to the block, use %x where x is the number of the input.

• script
  String
  Required
  The name of the script to call for this block. This can be anything you want. Spaces and non alphanumeric characters should not be used.

• network
  Boolean
  Required
  Whether your block requires network/internet access to run. If set to true, PiBakery will wait up to 2 minutes before trying to run the block, attempting to connect to a network. As soon as a network is found, or 2 minutes passes, the block's script will be run.

• continue
  Boolean
  Required
  Whether other blocks can be added after your block. This should normally be set to true, unless your block restarts or shuts down the Raspberry Pi, preventing other blocks from running.

• type
  String
  Required (legacy)
  The category of the block. This is used in older version of PiBakery to group blocks of a similar type together. To keep backwards compatibility with those versions, please include this as well. Can be:

  • software for a block that installs a new program
  • network for a block that modifies network connections and setting or downloads/uploads files
  • setting for a block that changes a non-network setting
  • other for anything else

• category
  String
  Required
  The category of the block. This is in PiBakery to group blocks of a similar type together. This can be any of the following, or if you have a group of blocks that are similar and don't fit into a existing category, you can create your own category and add your blocks to that. For more information on this, email david@pibakery.org. The current existing categories are:

  • software for a block that installs a new program
  • network for a block that modifies network connections and setting or downloads/uploads files
  • setting for a block that changes a non-network setting
  • otg for a block that changes the Pi Zero OTG settings
  • other for anything else

• shortDescription
  String
  Required
  A short description of the block. This is used as the tooltip when a user hovers over the block, so try to keep it as short and concise as possible

• longDescription
  String
  Required
  A longer description of the block. This is displayed when the user right-clicks on the block. When writing the long description, try to include:

  • What the block does
  • What each of the inputs of the block do, and what values should be entered into each
  • Whether the block needs network access or not

• args
  array
  Required
  Information about each of the arguments for your block. If your block has no inputs, leave this as an empty array. Otherwise, this should be an array of objects, with each object relating to one block input, and having the following properties:

  • type
    String
    Required
    The type of input for the block. Can be number for a field that will only accept numbers, text for a field that will accept all types of text, and menu for a dropdown menu where you can specify which options can be chosen.

  • default
    String
    Required for inputs of type text and number
    The default text or number inside the input. For no default text, set this to blank.

  • maxLength
    String
    Required for inputs of type text and number
    The maximum number of characters that input can handle. Useful for password fields where the number of characters is limited.

  • options
    String
    Required for inputs of type menu
    An array of the different options that can be selected. The first item in the array is used as the default option.

3. Create script file

Once you've created and edited your block JSON definition file. you'll need to create and edit the script file for your block to run. Create a file of the same name that you defined as the script property in your JSON file, and save it into your block folder.

You then need to add the appropriate shebang to the top of your script? What's a shebang? A shebang is the first line of the script that tells the Raspberry Pi what program to use to run your script. It is very important that you add this line, otherwise PiBakery might not be able to run your script. For example, the first line of a Python file would be #!/usr/bin/python and the first line of a bash file would be #!/bin/bash. For more information on shebangs, what they are and how they work, have a look at the Shebang Wikipedia article.

Then all you have to do is write you script for your block! The inputs from the block are passed as command line arguments, with %1 as the first argument, %2 as the second, and so on.

When writing your script there are a few things you should remember:

• The script will be run without any user interaction. This means you can not have any user input of any sort, as the user will not be able to respond, and it will appear as if PiBakery has crashed
• Your script will be run with and without a network connection. Although you can specify whether your script needs a network connection using the network property in the JSON file, this is used by PiBakery to try and establish a network connection before running your script, and has no guarantee that it will be successful. Try to make your script exit gracefully if it can not run.
• Whilst your script is run, the Raspberry Pi will show a loading screen, and therefore can not be used with a keyboard and mouse until all the scripts have run. You should therefore try and make your script as quick as possible, and never create a script that loops forever. These blocks will not be accepted into PiBakery, as they would have a detrimental effect on the user experience.

4. Test Your Block

Now that you've got your block folder with your JSON file and script file finished, you'll want to test it out with PiBakery. Luckily, this is simple to do, but you will need to have the latest version of PiBakery installed, so if you haven't already, download it now.

All you need to do is open PiBakery, and then drag your block folder onto the workspace. You'll see a message saying that your block was imported, and from then on, you can use that block from the toolbox, just as you would with any other PiBakery block. The only difference is that the block will disappear from PiBakery as soon as you close the program, however you can simply drag it in again to continue testing.

Note: Some users have reported that dragging and dropping the block folder does not work on some versions of Windows. If this happens to you, please use the keyboard shortcut CTRL shift + and choose your block folder in the selection window that will appear.

5. Submit to PiBakery

If you've made and tested your own block, you're ready to submit it to PiBakery so everyone can use it!

To submit your block, you'll need to be familiar with Git and GitHub. If you're not - it's a great thing to learn, and if you really don't want to, or are having trouble, tweet @PiBakery or email david@pibakery.org and I'll be happy to help.

There is a GitHub repository for the blocks of PiBakery. You'll need to fork this repository, add your block in and then submit a pull request so I can add your block in to the main repository. Once it's added in, an update will be pushed out, so everyone using PiBakery can choose to update and get your block.