[Boards Manager] Add tutorial for package_name_index.json

[NicoHood]

Hi,
I want to add 2 new board definitions to the board manager. Do you generate the .json file or do I have to do that? I have no idea how to format it and how to get informations like the checksum or size.

My board files:
https://github.com/NicoHood/HID
https://github.com/NicoHood/HoodLoader2

The documentation I found:
https://github.com/arduino/Arduino/wiki/Unofficial-list-of-3rd-party-boards-support-urls
https://github.com/arduino/Arduino/wiki/Boards-Manager-FAQ
https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5---3rd-party-Hardware-specification

[per1234]

• You have to generate the json.
• Checksum can be calculated with many different utilities I use md5deep.
• Size is just the size in bytes of the compressed install file. For example you can get this information in Windows by right clicking on the file, selecting Properties, and copying the value listed after Size:

I've done 3 of these now and am happy to help you(and anyone else who wants help with this process) with adding Boards Manager install support. I have commented on your HID issue 35 with details.

I agree it would be nice to have a tutorial. The way I figured it out is by looking at the list and copying what others had done.

Note: if you mess up the structure of the json file and add the URL to your Preferences it can cause the IDE to no longer load until you have deleted the files from your Arduino15 folder.

[per1234]

I looked around for a tutorial and couldn't find one so I made an attempt at creating one:
http://playground.arduino.cc/Main/BoardsManagerSupport *Edit: cmaglie wrote a much better documentation.
Any contributions, corrections, or feedback are welcome.

[cmaglie]

@per1234
I started documenting the package_index.json format here: https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5---3rd-party-Hardware-specification#hardware-folders-structure

It's not exactly in the form of a tutorial, but I hope it's a good starting point...

Would you like to merge your page on the playground on the github wiki? I'd like to put all the "official" documentation here on github.

[cmaglie]

Sorry wrong link, here the correct one:

https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.6.x---package_index.json-format-specification

[per1234]

@cmaglie Wow, very nice to have the format documented, thanks! Looks like I was a day early. I agree that it is better to have a single location for the documentation and that the Github wiki is the best place. I'd be happy to move any useful information from my playground page and then delete that page. Your documentation is much more informative but also a bit more complicated. I think anyone who can put together a 3rd party hardware project should be able to figure it out though.

Here are the things I think I could contribute, let me know what you think:

1. Change the order of the Tools and Platforms documentation. Platforms fields come first in all the json index files I've seen and for simple implementations no tools are needed.
2. Marking fields as optional - this seems like very useful information so people don't have to trial and error to see if leaving their email out, etc. will break the index.
3. Explanation of the archive folder structure.
4. Sample json index file and boards manager screenshot.
5. Possible Github file locations? This might be a bit too specialized but it seems to be the biggest issue to be decided on all the projects I've added Boards Manager install support to so far.

I have a couple questions:

1. What are the supported archive file formats? I see people using .zip and .tar.bz2 but it would be nice to have a full list.
2. You didn't document the help: online: field of _PACKAGE_XXXX_. I see that field in the Arduino package_index.json but it doesn't seem to do anything in Boards Manager, is that field deprecated?

[cmaglie]

Looks like I was a day early

Actually I've been working on that from some days, you just pushed me to release it quickly so, thanks! :-)

Change the order of the Tools and Platforms documentation. Platforms fields come first in all the json index files I've seen and for simple implementations no tools are needed.

I reversed the order because I thought that explaining first "tools" and in particular that tools are uniquely identified using the triple (packager, toolname, version) would help later when this identifier is used in the platforms' "toolsDependecies" field. If you explain the platforms first you need to anticipate this concept.

BTW, if you think that it's ok, go on and let's see how it looks. (I'm not a native speaker, so sometimes I miss simpler wording solutions :-))

Marking fields as optional - this seems like very useful information so people don't have to trial and error to see if leaving their email out, etc. will break the index.

Some field are optional in the sense that they can be left empty, BTW it's better if all the fields are filled to guarantee a better user experience, so I'd like leave the "optional" out.

Explanation of the archive folder structure.

(y), do you have already an idea or you need more info?

Sample json index file and boards manager screenshot.

Excellent

Possible Github file locations? This might be a bit too specialized but it seems to be the biggest issue to be decided on all the projects I've added Boards Manager install support to so far.

Using github to host the platforms is not mandatory, so it should be not part of the specification. Maybe we can do it an "Appendix" that explains how the platform can be hosted through Github? another thing to consider is that Github doesn't guarantee that the generated .zip files are immutable, so at some point the checksum may change, I guess that the only recommended method to host files on Github should be the Github's Tag/Release.

What are the supported archive file formats? I see people using .zip and .tar.bz2 but it would be nice to have a full list.

.zip
.tar.bz2
.tar.gz

You didn't document the help: online: field of PACKAGE_XXXX. I see that field in the Arduino package_index.json but it doesn't seem to do anything in Boards Manager, is that field deprecated?

I've documented it!

help/online: is a URL that is displayed on the Boards Manager as "Online Help"

Thanks!

[per1234]

I'm not a native speaker, so sometimes I miss simpler wording solutions

I am so I'll edit the obvious ones.

Using github to host the platforms is not mandatory, so it should be not part of the specification. Maybe we can do it an "Appendix" that explains how the platform can be hosted through Github?

Understood, maybe the Playground would be a more appropriate location for that.

another thing to consider is that Github doesn't guarantee that the generated .zip files are immutable, so at some point the checksum may change, I guess that the only recommended method to host files on Github should be the Github's Tag/Release.

I have already run into that problem with attiny and noted it in my tutorial. I haven't had any problems with archives that are manually added to a branch and Adafruit and Sparkfun are also using that system.

I've documented it! help/online: is a URL that is displayed on the Boards Manager as "Online Help"

In the Arduino _package_index.json_ it appears in two locations:

  "packages": [
    {
      "name": "arduino",
      "maintainer": "Arduino",
      "websiteURL": "http://www.arduino.cc/",
      "email": "packages@arduino.cc",
      "help": {
        "online": "http://www.arduino.cc/en/Reference/HomePage"

and under platforms:

          "name": "Arduino AVR Boards",
          "architecture": "avr",
          "version": "1.6.3",
          "category": "Arduino",
          "help": {
            "online": "http://www.arduino.cc/en/Reference/HomePage"

You documented it under platforms but not under packages and I didn't see that the help/online field under platforms had any effect in Boards Manager so I wondered if it was accidentally left out of the documentation or not.

I'll break my contributions up into multiple logical edits, feel free to revert anything you don't like or ask me to make changes.

[per1234]

@NicoHood have you checked out the documentation? What do you think? Let me know if you spot typos or something doesn't make sense.

[NicoHood]

I looks good. I just have no time to read it sorry. I really appreciate your help, thanks so much for your 2 PRs.

[per1234]

Unless there are any changes I need to make to my edits, I think this issue can be closed and I'll delete my tutorial from the Playground.

[cmaglie]

Looks good to me, thanks!