Skip to content

Getting started with the SIMHUB STANDARD ARDUINO PRO MICRO LEDs sketch

Jump to bottom
Wotever edited this page May 16, 2024 · 12 revisions

Getting started with the SIMHUB STANDARD ARDUINO PRO MICRO LEDs sketch

This version has been replaced by a new version : https://github.com/SHWotever/SimHub/wiki/SIMHUB-STANDARD-ARDUINO-PRO-MICRO-sketch-V2/

Introduction

This firmware (arduino pro micro sketch) is intended for small productions of commercial leds based devices. It is compatible with ATmega32U4 with Arduino bootloader (Arduino pro micro, Arduino leonardo). It is intended to simplify end user device usage (at the price of a little more configuration while building the firmware.)

This requires a dedicated PID/VID so SimHub can recognize the device without requiring the user to choose the serial port. That's why this firmware can't run on any standard arduino uno, arduino nano or arduino mega.

The sketch is a skeleton giving all the minimal code to make the leds work, other features like controller etc, can be added on your side. In order to port this protocol to another platform you can refer the the protocol description given at the end of this document.

Overall using this sketch is not the only way to do and is not intended to constrain manufacturers, if you are building your commercial device and have already done your firmware, want a deeper integration etc ... Please contact me at https://www.simhubdash.com/simhub-contact/ so we can evaluate the possibilities.

Download

The required sketch and utility can be downloaded here : https://www.simhubdash.com/official/ProMicroStandard/ProMicroSimhubStandardLedDriver_v1.1.zip

  • 15/09/2023 v1.1 Update : added unique id support (allowing multiple device instances of the same kind)

Sketch features overview

The sketch can aggregate up to 4 RGB LEDS strips (WS2812B Neopixels and/or PL9823), each one having it’s data pin, each strip can have its direction reversed. Ideally LEDS must be ordered in end user logic (telemetry LEDS then buttons …)

Arduino best feature is the ability to flash it but it’s also its biggest weakness when it comes to commercial products. To reduce unwanted flashes, sketch offers a basic upload lock security. Upload will be locked after 15 seconds (can be customized) after the device is plugged. This can be unlocked by sending either the upload unlock command or unplugging/plugging the device.

Create your firmware

Environment installation

image

Adding a custom board to the Arduino IDE with your PID/VID

  • Choose/buy your USB PID/VID.
  • Go into the Arduino IDE installation folder and inside the hardware\arduino\avr folder (ie : C:\Program Files (x86)\Arduino\hardware\arduino\avr on a standard installation)
  • Make a backup of the boards.txt file
  • Open the notepad as an administrator and edit the “boards.txt” file and add to the end the following section
##############################################################

custom32u.name=Custom Atmega32U
custom32u.vid.0=0x2341
custom32u.pid.0=0x0036
custom32u.vid.1=0x2341
custom32u.pid.1=0x8036
custom32u.vid.2=0x2A03
custom32u.pid.2=0x0036
custom32u.vid.3=0x2A03
custom32u.pid.3=0x8036

custom32u.upload.tool=avrdude
custom32u.upload.protocol=avr109
custom32u.upload.maximum_size=28672
custom32u.upload.maximum_data_size=2560
custom32u.upload.speed=57600
custom32u.upload.disable_flushing=true
custom32u.upload.use_1200bps_touch=true
custom32u.upload.wait_for_upload_port=true

custom32u.bootloader.tool=avrdude
custom32u.bootloader.low_fuses=0xff
custom32u.bootloader.high_fuses=0xd8
custom32u.bootloader.extended_fuses=0xcb
custom32u.bootloader.file=caterina/Caterina-Leonardo.hex
custom32u.bootloader.unlock_bits=0x3F
custom32u.bootloader.lock_bits=0x2F

custom32u.build.mcu=atmega32u4
custom32u.build.f_cpu=16000000L
custom32u.build.vid=0x8881
custom32u.build.pid=0x8882
custom32u.build.usb_product="My device name"
custom32u.build.board=AVR_LEONARDO
custom32u.build.core=arduino
custom32u.build.variant=leonardo
custom32u.build.extra_flags={build.usb_flags}
  • Edit the pasted code and modify the following lines to set your own values :
custom32u.build.vid=0x8881
custom32u.build.pid=0x8882
custom32u.build.usb_product="My device name"
  • Save the file

Configuring the sketch

  • Open the Arduino IDE and open the ProMicroSimhubStandardLedDriver.ino sketch and review all the settings to match your device (Led strip settings are repeated 4 times).
//-------------------------
// ------- General sketch informations
//-------------------------
// This sketch is delivered as simple SimHub compatible arduino pro micro leds driver. 
// See joined documentation for details about using it.

//-------------------------
// ------- Upload protection settings
//-------------------------
// Set to 1 to enable upload protection, upload from arduino IDE will be disabled after the specified delay (UPLOAD_AVAILABLE_DELAY),
// This can be unlocked using one of the following ways :
// - by unplugging/plugging back the arduino, upload will be enabled for the defined time.
// - by sending the magic string on the serial port : (0xFF)(0xFF)(0xFF)(0xFF)(0xFF)(0xFF)unloc
#define ENABLE_UPLOAD_PROTECTION 1
// Delay (in ms) after the arduino startup (plug/unplug/reset) where the upload will be available, after this delay upload will be locked.
#define UPLOAD_AVAILABLE_DELAY 15000

//-------------------------
// ------- LED STRIP X Settings
//-------------------------
// How many leds on this strip? Set to 0 to disable.
#define STRIP1_RGBLEDCOUNT 39
// Data pin
#define STRIP1_DATAPIN 6
// 0 left to right, 1 right to left
#define STRIP1_RIGHTTOLEFT 0
// Strip type (NEOPIXEL = WS2812B compatible, PL9823 = PL9823)
#define STRIP1_TYPE NEOPIXEL

TIP : Don’t enable upload protection (ENABLE_UPLOAD_PROTECTION) in the first stages so you can work conformably with Arduino IDE.

Uploading the sketch

  • Choose the previously created “Custom Atmega32U” in the boards menu (NB : See annexes if the custom board is not visible)

image

  • Select the serial port and upload

Notes :

  • If upload protection was enabled to upload once again the sketch, unplug/plug back the board to allow upload (see Upload protection settings in sketch), or you can use the provided utility.
  • After the first upload, device serial port name will change (as it is linked to the PID/VID)

Testing and maintenance utility

Sketch comes with a testing and update utility, it allows to quickly test the device.

image

Once the serial port is selected PID and VID of the target device get recalled so you can check it’s correctly taken into account.

Device maintenance commands

  • Unlock upload : Will disable the upload protection until the next board reboot.
  • Get protocol version : reads the protocol version, should be SIMHUB_1.0
  • Read leds count : gives back how many leds in total are configured on the board.
  • Show XXXX/Clear all leds : Allows to quickly test the leds.

Firmware update

Once your firmware is ready it can be exported using the Arduino IDE

image

Two files ProMicroSimhubStandardLedDriver.ino.leonardo.hex and ProMicroSimhubStandardLedDriver.ino.with_bootloader.leonardo.hex will be generated in the sketch folder.

image

Take the ProMicroStandardLedDriver.ino.leonardo.hex (Caution : Never use the with_bootloader version)

You can now upload it using the testing utility:

image

image

Adding the device inside simhub

  • In the device section click on add device, then on the bottom left click on create a standard device

image

image

  • Choose the combination you want to use :

image

  • Configure the PID/VID choosen while building the firmware so Simhub can find automatically the serial port and click apply :

image

  • The device should now connect (if you had the arduino support enabled, you might need a simhub restart)

Sharing your device definition

  • Lock the USB settings so they can't be changed anymore :

image

  • Set a picture for your device (ideally with a transparent background) :Right click on the picture and click on replace picture
  • Define your device name : click on rename device
  • Export your device (click on export device settings)

You can now use this file along your device. It contains all the settings (leds profiles ....)

Annexes

Troubleshooting: Custom board is not visible in Arduino IDE

If the board does not show please verify that you got the board correctly added. You might also need to clear arduino cached files.

  • Go into Arduino IDE preferences and get the settings directory (here : C:\Users\Nicolas\AppData\Local\Arduino15)

image

  • Make a backup of the folder
  • Remove all subfolders.
  • Restart the IDE

Protocol reference

Serial communication: 115200bps, DTR = ON, RTS = ON Replies are terminated by (0x0d)(0x0a) (\r\n)

Unlock upload

  • Send (0xFF)(0xFF)(0xFF)(0xFF)(0xFF)(0xFF)unlock
  • Reply: Upload unlocked\r\n

Note: supporting this instruction is not mandatory to get SimHub working.

image

Protocol version

  • Send (0xFF)(0xFF)(0xFF)(0xFF)(0xFF)(0xFF)proto
  • Example reply: SIMHUB_1.0\r\n

Note: SIMHUB_1.0 is the current protocol version.

image

Get led count

  • Send (0xFF)(0xFF)(0xFF)(0xFF)(0xFF)(0xFF)ledsc
  • Example reply: 32\r\n

image

Send led data

  • Send (0xFF)(0xFF)(0xFF)(0xFF)(0xFF)(0xFF)sleds(RL1)(GL1)(BL1)(RL2)(GL2)(BL2) .... (0xFF)(0xFE)(0xFD)
  • Reply: N/A

Note: message is terminated by a 3 bytes constant ((0xFF)(0xFE)(0xFD)) so a basic message integrity check can be done

image

Clone this wiki locally