So you've designed a microcontroller board that runs CircuitPython and you would like to show it off to the world by adding it to the circuitpython.org website? We can show you how.

Or perhaps you now have Blinka running on your Linux-based Single Board Computer (SBC) and want to share that to everyone? We can show you how to do that too.

There are two sections where you can add boards. The first is the downloads page for microcontrollers running CircuitPython and that will not only show off the details of your board, but provide links to download the latest stable and development releases of CircuitPython. If you haven't yet added your board to CircuitPython itself, first follow the instructions in the How to Add a New Board to CircuitPython guide.

The other section is the Blinka page which house all of the boards that support Blinka, which is our CircuitPython library compatibility layer for SBCs and Python 3. This page allows your to display all of the stats for your board as well as point to a guide for setting up Blinka on your board.

The Process

Either way, the process is about the same. Adding a board to the circuitpython.org website is easy and only requires three images and one Markdown or MD file per board.

Getting setup is very easy. The first thing you'll need to do is head over to Github and create a fork. If you would like more information, be sure to check out our Contribute to CircuitPython with Git and GitHub guide.

The repository to create a fork of is https://github.com/adafruit/circuitpython-org. Once you create a fork, you will need to clone it with git and you will have access to all of the source files for the website.

Let's continue with preparing our images!

Images should ideally show a clear view of the board with a little space between the board and the edge of the photo. It should also be free of text other than what is printed on the board itself. This will help to keep it consistent with the existing images.

To add a board to CircuitPython.org, you will need three sizes of the same image for each board.

1. Small Size Minimum Width of 292 pixels. (Most photos are 300x225 or 293x225)
2. Large Size Minimum Width of 590 pixels. (Most photos are 800x600 or 780x600)
3. Original Size Photo in a Large Size

A good aspect ratio that looks nice for the photo size is 13:10 or 4:3. These are the ratios used for most of Adafruit's product photos. We will start with finding an image, if you don't already have it, resizing it to the appropriate size, and optimizing it for the website.

Finding Images on Flickr

Adafruit has many products available on Flickr in high resolution. Most of the photos are in the 4:3 or 13:10 aspect ratios.

1. Go to https://www.flickr.com
2. Type "Adafruit Industries" into the search box and click "Search people"
3. Click on Adafruit Industries

Click the Magnifying Glass icon on the right

At the top, type in your Search Term and press enter

Click on a Photo in the Search Results

Verify the Description matches the item that you're looking for

Click the Arrow icon on the right side and select a size that will be your Original Sized photo

Resizing Photos

Photos can be resized in your favorite photo editor such as PhotoShop or GIMP or via websites such as ezgif.com

PhotoShop

PhotoShop is one of the most popular pieces of Photo Editing software by Adobe, however it is not free. Here are the steps to resize the image in PhotoShop.

1. Open the Original Sized Photo
2. Go to Image→Image Size...
3. Type a width like 800. The height should automatically adjust.
4. Press OK
5. Go to File→Export→Export As...
6. Select JPG for your Format and you can leave the quality as 100%
7. Click Export All... and save the file into a folder where you'll remember it. Choose a filename appropriate to your board.
8. Click Edit→Undo until you undo the resizing of the image
9. Repeat at step 2 for the small sized image, except choose something like 300 for the width

GIMP

GIMP, which stands for Gnu Image Manipulation Program is another very popular, but free piece of software. Here are the steps to resize an image in GIMP.

1. Open the Original Sized Photo
2. If it asks about Converting to RGB Working Space, click Convert
3. Go to Image→Scale Image...
4. Type a width like 800. The height should automatically adjust
5. Press Scale
6. Go to File→Export As...
7. Select JPG for your Format and you can leave the quality as 100%.
8. Click Export to save the file into a folder where you'll remember it. Choose a filename appropriate to your board.
9. Click Edit→Undo until you undo the resizing of the image
10. Repeat at step 2 for the small sized image, except choose something like 300 for the width

ezgif.com

ezgif.com is a website that provides all kinds of free image manipulation tools. This is a great option if you don't want to install any software on your computer. Here are the steps to resize the image in ezgif.com.

1. Navigate to https://ezgif.com/resize in your browser
2. Click Choose File and select your image
3. Click Upload!
4. Type a value like 800 into the width box and 600 into the height box.
5. Under If the aspect ratio does not match you can either leave it as Center and crop to fit or change it to Stretch to fit depending on which result looks better to you.
6. Click Resize image!
7. Scroll down and under the resized image, click save
8. It will download as ezgif.com-resize.jpg into your downloads folder
9. Find it in your downloads and rename it to something more appropriate
10. Repeat for the small sized image, except choose something like 300 for the width

Optimizing Images

Use your favorite image optimization website such as compressjpeg.com which we will cover.

1. Navigate to https://compressjpeg.com/ in your browser
2. Drag and drop all of your images into the area labeled Drop Your Files Here
3. Once they are done automatically compressing, click the Download All button
4. Unzip the file that downloads
5. If you had several similar filenames for the same board, you can look at the file size to determine the appropriate file.
6. Rename the files to the final name you would like to use.

Your images should now be ready for adding a board.

The Downloads section is for microcontroller boards which incorporate CircuitPython compatibility. If you have a Single Board Linux computer, see the Adding to Blinka page.

Image Location

Once you have your images prepared, you will want to place them into the three folders inside assets/images/boards as follows:

1. The Original Sized image should be placed into the original folder.
2. The Larger of the two resized images should be placed into the large folder.
3. The Smaller of the two resized images should be placed into the small folder.

All three images should have the same filename.

Markdown File

The markdown file contains all of the information used for the board. To create a Markdown file for your board, go into the _boards folder and make a duplicate of the unknown.md file.

You will want to rename the duplicate to something like board_name.md to match your image files. For instance, if your images were named feather_m4_express.jpg, you would want to use feather_m4_express.md.

Open up the new markdown file in your favorite text editor. This should be a text editor like Windows notepad and not a word processor such as Microsoft Word because word processors add extra data that will not work well with the Markdown file format.

We'll start with the header section and go line by line to make sure you have the correct information added. The header section always starts with three hyphen characters and ends with three hyphen characters. You can always look at the other Markdown files for examples too. We're going to take a look at the Feather M4 Express file.

Header

layout

Leave this set to download since we're on the downloads page

board_id

This should be the name of the board for example "feather_m4_express".

title

This is the page title and should be more descriptive and end with the word Download. For example "Feather M4 Express Download".

name

This is the name of the board and should be the same as Title but without the word Download. For example "Feather M4 Express".

manufacturer

The name of the board manufacturer. For example "Adafruit".

board_url

This is a full URL that the use to view the product information for the board. For example "https://www.adafruit.com/product/3857".

board_image

This is the filename only for the image you created. The path for the appropriate sized will automatically be generated. For instance "feather_m4_express.jpg".

date_added

This is the date the board was added to CircuitPython, or if you're not sure, you can just use the current date. The format is YYYY-M-D with a 4-digit year, 1 or 2 digit month, and 1 or 2 digit day. In this case, the date it was added was March 8, 2019 or "2019-3-8".

family

This is the bootloader family and should correspond to one of the values in here such as atmel-samd.

bootloader_id

This is the bootloader ID and should be included, if available, on bootloader certain bootloader families that have a version number in the file above. To find the ID, you can look in the following repositories:

• atmel-samd: https://github.com/adafruit/uf2-samdx1/releases
• nrf52840: https://github.com/adafruit/Adafruit_nRF52_Bootloader/releases
• esp32s2 or esp32s3: https://github.com/adafruit/tinyuf2/releases

downloads_display

This can optionally be included in order to hide your board by setting it to false. Omitting this value or setting it to true will display your board. The value should be true or false.

features

This is a list with features that the board has such as Battery Charging, Bluetooth, WiFi, etc. Items in this list are preceded by two spaces, a hyphen character, and another space. Features should be limited to the items in this list and spelled exactly the same:

• Arduino Shield Compatible
• Battery Charging
• Bluetooth/BTLE
• Breadboard-Friendly
• Feather-Compatible
• Display
• Camera
• External Display
• Feather-Compatible
• GPS
• LoRa/Radio
• Robotics
• Solder-Free Alligator Clip
• Speaker
• STEMMA QT/QWIIC
• USB-C
• Wi-Fi
• Xiao / QTPy Form Factor

Body

The body is more free form and should include at least one paragraph for a description of the board. This is often copied from a product page.

Purchase Section

If a board is available for purchase, it should include a Purchase section with one or more links. The link text should be the name of the website it linked to such as Amazon, Adafruit, AliExpress, etc.

Learn More Section

This section is more commonly found on pages where the board is not yet available for purchase. This should include informational links about the board. The link text should be the name of the website it linked to such as GitHub, NVIDIA, etc.

Submit a Pull Request

Now that you have your changes made, go ahead and commit your code to Github and submit a Pull Request. It will be reviewed and if it looks good, it will be merged in.

For Linux-based Single Board Computers, you will want to add the new board to the Blinka section of the website.

Image Location

Once you have your images prepared, you will want to place them into the three folders inside assets/images/boards as follows:

1. The Original Sized image should be placed into the original folder.
2. The Larger of the two resized images should be placed into the large folder.
3. The Smaller of the two resized images should be placed into the small folder.

All three images should have the same filename.

Markdown File

The markdown file contains all of the information used for the board. To create a Markdown file for the board, go into the _blinka folder and make a duplicate of one of the other files.

You will want to rename the duplicate to something like board_name.md to match your image files. For instance, if we're going to add the Raspberry Compute Module 3, we'll make a copy of raspberry_pi_3b.md because the board is the most similar to the board we're adding. We'll name it raspberry_pi_cm3.md and we'll makes sure all of the images are named raspberry_pi_cm3.jpg.

Open up the new markdown file in your favorite text editor. This should be a text editor like notepad and not a word processor such as Microsoft Word because word processors add extra data that will not work well with the Markdown file format.

We'll start with the header section and go line by line to make sure you have the correct information added. The header section always starts with three hyphen characters and ends with three hyphen characters. You can always look at the other Markdown files for examples too.

Here's the file that we're starting with.

Header

Let's take a look at the Header Options. You may notice that there's a few more here than the downloads page has.

layout

Leave this set to download. Even though this is the Blinka page, the layout should be the same as the download page.

board_id

This should be the name of the board for example "raspberry_pi_cm3".

title

This is the page title and should be more descriptive and end with the word Download. For example "Raspberry Pi Compute Module 3 Download".

name

This is the name of the board and should be the same as Title but without the word Download. For example "Raspberry Pi Compute Module 3".

manufacturer

The name of the board manufacturer. For example "Raspberry Pi Foundation".

board_url

This is a full URL that the use to view the product information for the board. For example "https://www.raspberrypi.org/products/compute-module-3/".

board_image

This is the filename only for the image you created. The path for the appropriate sized will automatically be generated. For instance "raspberry_pi_cm3.jpg".

download_instructions

This should be the full URL that points to the appropriate setup guide. For example "https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi". Leave it blank if there are no board setup instructions.

downloads_display

This can optionally be included in order to hide your board by setting it to false. Omitting this value or setting it to true will display your board.

blinka

This value should always be set to true. This tells the downloads layout to look for the additional Blinka page header options.

date_added

This should be the date that the new board was merged in and released in Blinka. It should be in the format of YYYY-M-D. 

features

This is a list with features that the board has such as Battery Charging, Bluetooth, WiFi, etc. Items in this list are preceded by two spaces, a hyphen character, and another space. Features should be limited to the items in this list and spelled exactly the same:

• Ethernet
• HDMI/DisplayPort
• Wi-Fi
• 40-pin GPIO
• GPS
• Feather-Compatible
• Bluetooth/BLE
• STEMMA QT/QWIIC
• USB 3.0
• Infrared Receiver

Body

The body is more free form and should include at least one paragraph for a description of the board. This is often copied from a product page. If this is available on the vendor website, this would be the preferred text. If not, we usually make it concise, but informational.

Purchase Section

If a board is available for purchase, it should include a Purchase section with one or more links. The link text should be the name of the website it linked to such as Amazon, Adafruit, AliExpress, etc.

Learn More Section

This section is more commonly found on pages where the board is not yet available for purchase. This should include informational links about the board. The link text should be the name of the website it linked to such as GitHub, NVIDIA, etc.

Final File

After editing the duplicated file, this is what it looks like. In this case, it was not available on adafruit.com, but was available through the Raspberry Pi Foundation website.

Submit a Pull Request

Now that you have your changes made, go ahead and commit your code to Github and submit a Pull Request. It will be reviewed and if it looks good, it will be merged in.

To test the changes locally, you before creating a Pull Request, you can run a copy of the the circuitpython.org website locally to see what everything looks like.

1. Open up a terminal or command prompt window.

2. You need "ruby" and "ruby-bundler" installed locally. Installation varies by system.

3. As needed, git submodule update --init --recursive to fetch the submodules.

4. One time, run bundle config set path 'vendor/bundle' && bundle install.

5. Run bundle exec jekyll serve 2>&1 to generate the site locally. The 2>&1 is optional and just suppresses a bunch of warning messages.

6. Visit the displayed server address in a browser.

After most local edits, the content will be updated. You will need to reload (ctrl-r/command-r or F5) your browser

Running Automated Checks

You can run the automated checks locally to verify it passes. You will first need to make sure you have the necessary packages installed on your system:

Make sure you are in the root folder of the circuitpython.org repository, then you can run the checks: