[Project] Brainstorm: sharing projects

[laurensvalk]

@GianCann, @Nelvarion, @ZPhilo, @Patlepirate01, and others: you've expressed some interest to maybe share some of your work. And we really appreciate that. Other users will be able to recreate your work and learn from it.

Instead of posting a set of strict rules right away, we'd like to encourage some discussion on what makes the most sense for you. And also to discuss what you think the broader community will want.

Please jump in with your ideas! If any of this doesn't make sense, please let us know.

Pybricks-projects

Everyone is welcome to post their creations and code anywhere they like, such as on your own blog, forum, or social media.

However, we make pybricks-projects available as a central resource as well. It would be great if this could be a resource of programs that work really well, to provide inspiration for others.

This could include anything from really simple demos to demonstrate a cool feature or basic technique, all the way up to complex programs that use almost all memory in the hubs.

Official sets vs. custom builds

We're thinking it makes sense to have only projects that people can really recreate.

This might have to be just the official sets. There are plenty of those already. Or maybe with some additional sensors or motors, color markers, etc.

But we'd love to get your feedback on it. Should we allow remix models / b-models? Perhaps only when you can include a link to free online building instructions? @ZPhilo, I think you built a program for an alternate model of the rock crawler that someone made. Would it fit in this category?

Maintainers

The Pybricks authors cannot possibly try out all the projects. We don't have all the sets and we don't have that much time. We'd like to encourage the submitter of a project to support it as well. So, when people create an issue about a project, we'd ask the creator of the project to answer those questions, and possibly repair the example program.

When someone else makes a pull request to change an example, we ask the maintainer to approve it. When the maintainer says yes, the Pybricks Authors will merge the change.

If multiple people report that something no longer works and the original author chooses not to update the project, another volunteer may take over and become the maintainer for that project. If no-one wants to maintain it and it does not work, we would remove it from the master branch.

This might sound strict or harsh, but the whole endeavor is really only useful if you know the projects you find here actually work.

Licensing

We'd like to keep things simple and publish everything under this MIT License so everything remains free to anyone.

Description requirements

We'd ask contributors to provide not only an example Python script, but also a short description (README.md) of what it does, and what you need to do to make it work.

We'd also ask you to make a basic video and upload it to something like Youtube. When you try a program, it is really helpful to see what the creation is expected to do. This doesn't have to be a fancy or edited video; just a short and basic demo of the program in action is fine.

Would this make sense? Or realistically, would it be too much work for contributors?

GitHub vs. not GitHub

Not everyone is familiar with Git/GitHub, and this can be quite a barrier to submitting projects.

So perhaps we can also allow projects to be shared as an issue, like this one. After all, writing a README.md file is just the same as posting an issue.

Then another contributor can commit it on their behalf. The original creator would still be responsible for updating errors and answering questions. Modifying existing stuff should be easy enough through the online interface.

Example of an example

We made one example project here to give you some ideas for what it might look like.

All in all, it is essentially just a program, a readme with explanation, and a demo video. We're curious to hear if you think the project format is feasible.

Thanks everyone! Please let us know if you have any questions, ideas, or concerns.

[GianCann]

I think it's all you have explained having a sense.

I have some doubts only in the division between projects: original and customized set.
Because some example could be a simple snippets of code to obtain a specific task (I think, for example, "How to catch the click on green button")

[Nelvarion]

I'm in favor of one README.md with links to simple tasks.
More complex scripts should have their own directory with step by step breakdown.

[laurensvalk]

Thanks for your responses.

@GianCann , there's also a snippet folder for that kind of thing, which is separate from models. But we will probably make most of those ourselves. For small examples it is usually less overhead to just make them ourselves compared to processing pull requests, and we'd like those small pieces to all have a similar style as well. I made two snippets for the Ultrasonic Sensor earlier today.

[scotus-49]

@laurensvalk
I would like to add some comments to your questions about user contributions.

First of all, it must be said, that the two of you have created something truly remarkable. It could now also lead to some other remarkable things, but equally, it could fall flat.

When I found your project website, and read your mission statement - Teach one million people real code - and your subtitle - Made by Experts, Built for beginners, I had at the same time, thoughts of -YES - but how?

It should be clear from your stated goals that the need now is for how-tos, tutorials and real learning information. How else do you reach the new million real coders? The ultimate test of any open source coding initiative still seems to depend on the quality and amount of the documentation. A how-to can be in a project form, but a project description is not necessarily a learning opportunity.

You have a detailed Roadmap for the next software version or whatever. But what in my opinion would now be more helpful could be a roadmap for reaching the goal of a million real coders.

I am not a professional coder, I am an architect. Maybe if I had not played with Lego as a kid I might have followed another path in life. But I create, and build, and, Lego still has, given the right approach, the possibility of allowing us to extend our creative imaginations.

I am not affiliated in any way with Lego, and find much to argue with concerning their policies and directions. For example, when I bought my Mindstorms EV3 set, about a third of the parts were missing, and even the official Lego Shop in town (Berlin) could do nothing except say sorry. It took about a whole month of internet messaging to Denmark to get the missing parts, with NO apology whatsoever from Lego.

In all your documentation so far available, there seems to be room to create and make available that needed information to fulfill your "Built for beginners" aim.

I would like to assist in any way that I can, to help fulfil your "Built for Beginners" aim.

I look forward to hearing from you.

Francis Sim
Berlin, Germany

[laurensvalk]

Thanks Francis, I appreciate your input. This is certainly an area where we are still testing the waters.

Our intentions to make it a long-term beginner-friendly project are not without substance, though. @dlech's ev3dev is still going strong after many years and I've written a few beginner-friendly books on related subjects (see e.g. English/German reviews to get an idea). We're hoping Pybricks can eventually grow this way to reach such audiences.

At the moment, from a development progress point of view, we feel we're not yet at the stage where we can fully take it to the beginner friendly level, but we expect to develop this plan over time. For the moment, it's perhaps more aimed at enthusiasts who know a bit of Python and who don't mind if a thing or two does not quite work yet. It's for this audience that these project examples for existing sets could be a nice entry point, and a way to grow the community.

[scotus-49]

@laurensvalk
Thanks for your thoughts.

You are most likely aware of an Italian competition to Lego EV3 etc, the firm Clementoni. Under the Galileo Science/Coding Lab brand they have released a series of products which cost a mere fraction of what we have to pay for Lego (around 50-60 Euros). Their sets are made in Italy, not part of the globalisation system as per Lego. The quality might be less than Lego, but not too many families have 300-500 Euros to splurge on Lego Spike or Mindstorms.

Clementoni have as a consultant Prof. Alessandro Bogliolo from the University of Urbino, co-ordinator of the European Code Week etc. I have followed several of Prof. Bogliolo's courses o robotics, in an online format, and although this stretched my knoledge of Italian somewhat. I found them extremely informative and educational.

In the extremely Informationsreich booklet to the RoboMaker Pro set, there is the following quote from Prof. Bogliolo:

"Die Konstruktion und die programmierung eines Roboters sind kreativ Handlungen, die Fantasie und Einfallsreichtum fördern."

Millions of beginning coders around the world have already cut their teeth on Micropython with the BBC Micro:Bit. Damien George hmself made this happen. The groundwork is there, it can and must be built on.

[Walt-White]

@laurensvalk
I'm one of the "enthusiasts who know a bit of Python" you mentioned, and I learn best by looking at examples and snippets. I used Pybricks version 1 for an EV3 train Great Ball Contraption module shown at Bricks By the Bay in Santa Clara, California, last summer, so I'm happy to see all the improvements in version 2.

I'm also very new to the Git/Github world and I'd like to share another train example, this one demonstrating Bluetooth messaging. I agree with @GianCann that I think a lot of people want to know how to accomplish a specific task like messaging and don't necessarily require the exact same hardware as the example.

My example also shows an example of the "try / except" technique used with the automatic motor/sensor detection. I don't know how much explanation that would require in a ReadMe file.

[laurensvalk]

Thanks for your input, @Walt-White. Perhaps then we can have three categories in pybricks-projects:

• snippets (included in API docs: short, simple, usually demonstrating one method)
• sets (complete programs for official models, as discussed in this topic).
• tricks* (projects with tips/tricks/techniques, without complete step-by-step instructions and material lists)

• If anyone has a better name for this category, feel free to suggest one

[XilefTech]

@laurensvalk
I think these categories are great in general, but there is something missing for complete programs that are not tied directly to one robot or Project, but could be used with many different kinds of robots. For Example what I'm working on with my CharlieOSX. I'd love to share that on there too, as soon as I get it to a presentable state, but I find it very hard to put it in one of those categories.

[laurensvalk]

Thanks @XilefTech. I think some bigger projects like yours might be best suited to stay in their own repository, like you are currently doing. That gives you all the freedom to develop your project.

What we could do at some point is provide a page or readme with additional links to such projects for inspiration.

[XilefTech]

that sounds like a good idea.
I anyway wanted to keep developing in my own repository and thought of only pushing major updates to the pybricks-projects page.
But a Readme with links and some info will also work I guess.

[laurensvalk]

Hey everyone. It took a while, but now it's possible to submit projects! 🚀

As you may have noticed, we have a new website with a dedicated projects section. Here's one example project.

If you want to share your Pybricks project like this, now you can. We've done our best to make it easy to get your project featured on our site. In essence, all you need is a picture, a video, a program, and README.md file as shown below.

---
permalink: /projects/sets/boost/auto-builder/
title: "LEGO Boost Auto Builder"
maintainer:
    user: "pybricks"
    name: "The Pybricks Authors"
image:
    local: "photo.jpg"
    credit: "LEGO"
video:
    youtube: "https://www.youtube.com/embed/TXvCEK1MNGQ"
description:
    "The Auto Builder builds LEGO figures autonomously. These Python scripts
    make it work smoothly and accurately."
building_instructions:
    external: https://www.lego.com/cdn/product-assets/product.bi.additional.main.pdf/17101_A_AutoBuilder.pdf
---

# Here you can add more information
Feel free to get creative here :)

Once those files are submitted to the projects repository like this, we can easily display it on the site.

If you're not familiar with GitHub, you can just paste the content above in a new issue and we'll take it from there.

We'll start with projects for official Powered Up sets, and we'll probably start allowing EV3 or custom projects later as well.