Online Arduboy Repository Format Guide


(Holmes) #1

With the release of the Arduboy package file standards, I figured I would release the repository guidelines that I’m using in the next version of my Arduboy Manager, which will include the new features we added. @mockfrog in onboard for adopting this format for his Arduboy Mate as well as possibly others.

Having a standard will allow anyone to make sharable repository of their own. :slight_smile:

Format

The repo will be an .json file that defines a series of games by giving the metadata contained in the games’ info.json files as well as links to the games’ images/binaries.

Example

{
  "repository": "Arduboy Manager Repo",
  "api-version": "1.0",
  "maintainer": "crait",
  "website": "http:\/\/www.crait.net\/",
  "email": "crait.is@gmail.com",
  "items": [
    {
      "title": "Arduboy Assistant",
      "description": "Arduboy Assistant allows you to view raw EEPROM data, back it up through the Arduino IDE's serial monitor, restore EEPROM data the same way, and even clear the entirety of the EEPROM data. Additionally, you can also test buttons, LED's, speaker, serial port, and screen.",
      "genre": "Application",
      "companion": null,
      "url": "http:\/\/www.crait.net\/",
      "code": "crait",
      "idea": "crait",
      "art": "crait",
      "sound": null,
      "publisher": "crait",
      "email": "crait.is@gmail.com",
      "date": "2017-1-12",
      "sourceUrl": "http:\/\/www.crait.net\/",
      "version": "1.1",
      "author": "crait",
      "buttons": [
        {
          "control": "Up",
          "action": "Menu Up"
        },
        {
          "control": "Down",
          "action": "Menu Down"
        },
        {
          "control": "A",
          "action": "Select"
        },
        {
          "control": "B",
          "action": "Back"
        }
      ],
      "banner": "http:\/\/www.crait.net\/arduboy\/arduboyassistant\/banner.png",
      "binaries": [
        {
          "title": "Arduboy Assistant",
          "filename": "http:\/\/www.crait.net\/arduboy\/arduboyassistant\/app.hex",
          "device": "Arduboy"
        }
      ],
      "screenshots": [
        {
          "filename": "http:\/\/www.crait.net\/arduboy\/arduboyassistant\/screenshot00.png",
          "title": "Screenshot"
        }
      ],
      "arduboy": "http:\/\/www.crait.net\/arduboy\/arduboyassistant\/ArduboyAssistant.arduboy"
    },
    {
      "title": "Circuit Dude",
      "description": "Help Circuit Dude build his secret invention by leading him through 50 unique levels, completing circuits and plugging in microchips. After all chips are inserted into their sockets, the exit will activate and you can advance to the next puzzle!",
      "genre": "Puzzle",
      "companion": "http:\/\/www.crait.net\/circuitdude\/",
      "url": "http:\/\/www.crait.net\/",
      "code": "crait",
      "idea": "crait",
      "art": "crait",
      "sound": "crait",
      "publisher": "crait",
      "email": "crait.is@gmail.com",
      "date": "2017-1-1",
      "sourceUrl": "http:\/\/www.crait.net\/",
      "version": "2.0",
      "author": "crait",
      "buttons": [
        {
          "control": "D-Pad",
          "action": "Move Circuit Dude"
        },
        {
          "control": "Hold A",
          "action": "Restart Level"
        },
        {
          "control": "A + B",
          "action": "Level Select"
        }
      ],
      "banner": "http:\/\/www.crait.net\/arduboy\/circuitdude\/banner.png",
      "binaries": [
        {
          "title": "Circuit Dude",
          "filename": "http:\/\/www.crait.net\/arduboy\/circuitdude\/CircuitDude.hex",
          "device": "Arduboy"
        }
      ],
      "screenshots": [
        {
          "filename": "http:\/\/www.crait.net\/arduboy\/circuitdude\/screenshot00.png",
          "title": "Title Screen"
        },
        {
          "filename": "http:\/\/www.crait.net\/arduboy\/circuitdude\/screenshot01.png",
          "title": "A very hard level!"
        },
        {
          "filename": "http:\/\/www.crait.net\/arduboy\/circuitdude\/screenshot02.png",
          "title": "Level 44"
        }
      ],
      "arduboy": "http:\/\/www.crait.net\/arduboy\/circuitdude\/CircuitDude.arduboy"
    }
  ]
}

Fields

The first layer of fields are:

  • repository: The title or name of the repository. Everyone’s should be different.
  • api-version: Standards followed the current repo. The standards in this guide are for 1.0, so please put that.
  • maintainer: Name of the person/organization who maintains the repo.
  • email: Optional e-mail address of the maintainer.
  • website: Optional URL for the maintainer’s or repository’s website.
  • items: An array of objects that contain all the game’s metadata and links.

Items

Each object in the items array should have all the fields and values that can be found in the game’s info.json file. The only differences are that instead of giving the filename for the screenshots, hex files, and banner, you need to provide the relative or absolute URL to those files. There is also a new field called arduboy, which will point to the direct URL of the game’s .arduboy file.

Requirements

All parent-level fields are required: repository, api-version, maintainer, and, of course, items.

Inside of each item, the minimum fields would be binaries, title, as well as arduboy.


[OLD] Arduboy Manager (PC)
(Timo Bußhaus) #2

@crait Great work! Do you think, we should support relative urls for item elements? that would make the repo file shorter, and better readable.

I hope I’ll find some time in the next few days, in order to implement complete .arduboy compatibility. But I don’t know for sure, since I’m going to attend #33c3 and that will keep me busy for sure :slight_smile:


(Holmes) #3

My bad!! Yes, relative and absolute URL paths ARE allowed! As long as they are directly pointing to the appropriate files!


(Holmes) #4

^ Fixed the sourceurl to be correct case of sourceUrl .


(Holmes) #5

^ Updated to match the new .arduboy features.


(Mike) #6

Which of the three loaders (AGL, Arduboy Manager and Arduboy Mate) support this now? In other words, if I tweak arduweb to support this, which of this can be used to test it?

Also, is there a list of which fields are required?

For that matter, is there a problem if I provide both an arduboy and a binaries field?


(Holmes) #7

Arduboy Manager, but @mockfrog’s Arduboy Mate is supposed to be updated to support it, soon.

For required fields, I’ll update the original post with that info.

You should really provide both since they both point to different things and different ways (in theory) of transfering the data to the Arduboy.


(Mike) #8

Is someone going to do a schema for this one as well? If not, would you be interested in one if I took a crack at it?


(Scott) #9

@mwm, If you’re going to take a crack at making a schema, you may wish to use this site to create a base. Setting the Include metadata keywords check box will add the “title” and “description” metadata keywords for each field.