Welcome to HJBricks

• 1: Overview
• 2: Concepts
• 3: Common configuration
• 4: Webserver
• 5: Setup CI/CU using gitlab
• 6: hjb devices
• 6.1: hjb throttle
• 7: Reference
• 7.1: Parameter Reference
• 8: Contribution Guidelines

1 - Overview

What is HJBricks?

HJBricks started because I wanted a remote for Rocrail^® so I could control locomotives without direct access to Rocview.

Features that all devices share:

• central remote updates of the firmware, configurable:
  • update on startup
  • update on an mqtt message
  • or both
• central remote configuration update:
  • update on startup
  • update on an mqtt message
  • or both

hjb-throttle

This remote, hjb-throttle, only needs access to the mqtt broker where Rocrail is connected to. Everything else is requested from Rocrail.

Version 1 has a custom PCB with some of-the-shelf pcb’s and a ESP32 added to it to make the electronics work, it has one 18650 Li-Ion battery that lasts for many hours and is rechargeable. And has a 3d printed housing to make it nice complete device.

I am open to suggestions for version 2.

hjb-layout

The next device is hjb-layout, this is still work in progress, it should be placed on the layout and controll the lights in your houses and controll motors in your layout.

The motor is a Lego^® PF connector (possible 2) and the lights can be controlled using a WS1128 board to control LEDS or just a Neo-pixel. Still contemplating if I should add support for:

• standard 2 pin LEDS
• a few servos It will be powered by a 3 pin connector and it should be small enough to place it in a modular building.

Maybe make the I²C bus daisy chain able to extend the IO ports.

The housing is 3D printable, probably resin because of the tolerances.

hjb-loco

A future extension, the case has to have two PF connectors for the engine controll, 3 pin for an WS1128 board to controll all the LEDs and as a later extension add a speaker for programmable sounds.

The minimum dimensions should be a 4x4x1 and maximal 4x8x3 bricks externally powered by a 2SLiPo.

Feel free to add your wishes at GitHub.

2 - Concepts

The rr-devices do not work on its own. It needs a number of components:

• Rocrail^® setup to use mqtt
• an mqtt broker
• WiFi

Rocrail

You get Rocrail from https://wiki.rocrail.net/doku.php?id=start. In Rocrail, open a plan then goto “File->Rocrail properties…”.

Probably save the plan and restart Rocrail to make the settings take effect.

MQTT broker

Any mqtt broker will do, the most used one is mosquitto, it you do not want to use a Username and Password, uncomment, or add a line in mosquitto.conf containing:

allow_anonymous true

The default listen port is 1883, if you change this, you should use this port number in any configuration, in Rocrail and any device you want to use with this mqtt broker. After all the changes (re)start mosquitto!

WiFi

As the remote is not on a wire, WiFi is needed, WPA2 should be enabled to make connection to the rr-devices.

Typical setup

In a typical setup you probably have Rocrail and mosquitto running on the same machine. You have an access point/wireless router somewhere that routes all the network traffic.

The layout is connected to the Rocrail server, or through WiFi.

---

Why a http server? The software can be updated using OTA, but also through an http server. At the moment during startup a firmware and configuration check is done, but it is optional.

3 - Common configuration

The throttle has the least complex configuration file, all other device build further on this file.

Human readable JSON configuration file

A non working example configuration file looks something like this:

{
    "version"  : 3,
    "hostname" : "CTRL01",
    "wifi": { "SSID": "ssid", "password" : "password" },
    "loglevel": "DEBUG", 
    "mqtt"   : { "broker" : "mqtt.example.com", 
                 "port"   : 1883,
                 "username" : "<not used>",
                 "password" : "<not used>", 
                 "ebreakOnDisconnect" : false },
    "update" : { "configUrl" : "http://192.168.178.10/esp/config/",
                 "manifestUrl": "http://192.168.178.10/esp/firmware/manifest",
                 "firmwareType": "esp32-rr2bricks-rrmaus"},
    "OTAPassword" : "<OTAPassword>"
}

Version

The version field contains the current configuration file version, always an integer and 3. The release notes will state if it is compatible and the firmware will not load an unsupported version.

Hostname

The hostname field is the hostname of this ESP, but also the map where the ESP will look for a new configuration on the webserver. The url where the ESP will search is <configURL>/hostname.

WiFi

The wifi section has two fields:

1. SSID : the WiFi ssid where the ESP32 has to connect to.
2. password : the WiFi password

Loglevel

loglevel can only have the following values:

• DEBUG
• INFO
• WARNING
• ERROR
• FATAL

mqtt

For the mqtt section the following fields must be defined:

1. broker : the name or IP address of the mqtt broker
2. port : the port number where the broker is listening to
3. username : the username, not yet used
4. password : the password, not yet used

update

All fields in update are optional, but is recommended to use them, it makes updating configurations and firmware quite easy.

The checks are done at boot time of the ESP32.

The configuration is is ESP hostname based, the base url is configured in configUrl the firmware is looking in configUrl hostname for updates in the configuration. If the sha-256 sum is different than the one stored on the EPS32 it will download this version and reboot to make the new configuration take effect.

The manifestUrl is the file where the EPS32 is looking for the latest firmware version, if it finds a newer one for the correct firmwareType it will download this version and reboot.

OTAPassword

The firmware also supports OTA updates, for this reason the OTAPassword is used, tit needs to be the same as the one used in the upload software (VSCode in this case.)

Generate configuration files for the ESP32

The JSON configuration file, generates three file, when convert_config_json2bin.py is called.

python ./convert_config_json2bin.py --src=./config/config.json --dest=./data

• ./data/config : binary configuration file;
• ./data/config.sha255 : the sha256 sum of the config file, needed to check at the ESP32 if the file has changed;
• ./data/hostname : the hostname of the ESP32

4 - Webserver

An ESP has the ability to do OTA update, which is easy when developing code. This firmware has the ability do pull firmware and configuration updates from simple webserver. All the webserver has to do is to serve some file that reside in specific directory.

In the device configuration, in the update section, the server location is configured. configUrl for the host based configuration and manifestUrl for the firmware location.

A good starting point for the directory structure would be as follows.

/esp/config
    /firmware

You are free to do as you wish as long as it is in line with the board configurations!

At the moment the firmware does not support https so all has to be http traffic.

A best practice is to make the webserver name based, this makes future IP address changes not such as hassle, don’t ask my why ;-)

5 - Setup CI/CU using gitlab

Before we go and setup a webserver, we need content for that server.

The following variables need to be set in gitlab, outside of any files in the CI/CD settings part of gitlab:

• SSH_PRIVATE_KEY
• SSH_HOST_KEY
• WWW_ROOT, the file system root of where the files are copied to;
• HTTP_ROOT, the base url where to get the firmware from

WWW_ROOT should be something like “/var/www/esp-hosting” (on a Linux system) HTTP_ROOT would be something like “http://esp-firmware.server.org”

image: python:3.10

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
  GIT_SUBMODULE_STRATEGY: recursive
  GIT_SUBMODULE_FORCE_HTTPS: "true"
  
cache:
  paths:
    - .pip-cache/

stages:
   - build
   - deploy-dev
 
build-throttle:
  tags:
    - platformio
  stage: build
  before_script:
    - pip install -U platformio
    - export GIT_DESC=$(git describe)
    - export arrV=(${GIT_DESC//-/ })
    - export VERSION=${arrV[0]}-${arrV[1]}
  script:
    - pio run -e esp32doit-devkit-v1
    - cp .pio/build/esp32doit-devkit-v1/firmware.bin esp32-hjb-throttle.bin
  artifacts:
    paths:
    - esp32-hjb-throttle.bin
    expire_in: 1 week

deploy-dev:
  tags:
    - platformio
  stage: deploy-dev
  dependencies:
    - build-throttle
  except:
    - master
    - release
  before_script:
    - apt-get update -y && apt-get install openssh-client bash rsync -y
    - eval $(ssh-agent -s)
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - eval "$(ssh-agent -s)"
    - ssh-add ~/.ssh/id_rsa
    - echo "${SSH_HOST_KEY}" > ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts
    - export GIT_DESC=$(git describe)
    - export arrV=(${GIT_DESC//-/ })
    - export VERSION=${arrV[0]}-${arrV[1]}
  script: 
    - if [ "$VERSION" == "-" ]; then export VERSION="0"; fi
    - scp esp32-hjb-throttle.bin ${WWW_ROOT}/esp/firmware/esp32-hjb-throttle-${VERSION}.bin
    - echo $VERSION # Do something with this variable
    - scp ${WWW_ROOT}/esp/firmware/manifest .
    - echo "esp32-hjb-throttle, "$VERSION", $HTTP_ROOT"esp/firmware/esp32-hjb-throttle-"$VERSION".bin >> ./manifest
    - scp manifest ${WWW_ROOT}/esp/firmware

After a success full run of the CI/CD build, the manifest file is updated, an example of the manifest file is:

esp32-hjb-throttle, D0.1-16, http://esp-firmware.server.org/esp/firmware/esp32-hjb-throttle-D0.1-16.bin

The contents of the firmware directory could look like:

esp32-hjb-throttle-D0.1-16.bin
manifest

6 - hjb devices

We call it hjb-devices, but for now we only have one.

If you are using gitlab, there is a .gitlab-ci.yml which builds all on commits to develop and master. And when committed toit, the moment only commits to develop, will lead to a deployment to a local webserver.

6.1 - hjb throttle

We call it hjb-devices, but for now we only have one.

7 - Reference

If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen, Javadoc, or other doc generation tools by putting them in your static/ directory. Find out more in Adding static content. For OpenAPI reference, Docsy also provides a Swagger UI layout and shortcode that renders Swagger UI using any OpenAPI YAML or JSON file as source.

7.1 - Parameter Reference

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

8 - Contribution Guidelines

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Netlify to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Quick start with Netlify

Here’s a quick guide to updating the docs. It assumes you’re familiar with the GitHub workflow and you’re happy to use the automated preview of your doc updates:

1. Fork the Goldydocs repo on GitHub.
2. Make your changes and send a pull request (PR).
3. If you’re not yet ready for a review, add “WIP” to the PR name to indicate it’s a work in progress. (Don’t add the Hugo property “draft = true” to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.)
4. Wait for the automated PR workflow to do some checks. When it’s ready, you should see a comment like this: deploy/netlify — Deploy preview ready!
5. Click Details to the right of “Deploy preview ready” to see a preview of your updates.
6. Continue updating your doc and pushing your changes until you’re happy with the content.
7. When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

1. Click Edit this page in the top right hand corner of the page.
2. If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
3. Follow the rest of the Quick start with Netlify process above to make, preview, and propose your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

1. Follow the instructions in Getting started to install Hugo and any other tools you need. You’ll need at least Hugo version 0.45 (we recommend using the most recent available version), and it must be the extended version, which supports SCSS.

2. Fork the Goldydocs repo repo into your own project, then create a local copy using git clone. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.

   git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
   

3. Run hugo server in the site root directory. By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.

4. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the Goldydocs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

• Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
• Hugo documentation: Comprehensive reference for Hugo.
• Github Hello World!: A basic introduction to GitHub concepts and workflow.