Skip to content
This repository has been archived by the owner on Nov 13, 2023. It is now read-only.

Latest commit

 

History

History
177 lines (125 loc) · 5.79 KB

BUILD.md

File metadata and controls

177 lines (125 loc) · 5.79 KB

Configuration, Build, and Installation

Bootstrap

In order to bootstrap Garaduino, some details will be required:

  • MAC address - a MAC address will need to be selected or created for the Ethernet interface. The Ethernet Shield may have a MAC address included on a printed sticker; if not, any MAC address can be used as long as it does not conflict with any other device on the network.

    Note: the default MAC address in Garaduino matches the one in the OTEthernet example sketch which is used below, so it is safe to use the default for basic testing of the build and bootstrap process.

  • Password - the OTA upload process uses a username/password combination to authenticate the uploader. The username is fixed as 'arduino', but the password can be any string of characters.

    Note: the default password in Garaduino matches the one in the OTEthernet example sketch which is used below, so it is safe to use the default for basic testing of the build and bootstrap process.

  • IPv4 address - Garaduino assumes that the network will use DHCP to provide an address, and since the address will be associated with the MAC address it will be obtained after the board has been bootstrapped.

To get started, launch the Arduino IDE, connect the Arduino to the computer over USB, and open the OTEthernet sketch.

  1. Click File->Examples->ArduinoOTA->OTEthernet.

  2. Enter the MAC address in the line which begins with byte mac[], replacing the existing MAC address.

  3. Enter the password in the line which contains ArduinoOTA.begin(), replacing the existing password string.

  4. Click the Upload button on the toolbar to compile and upload the OT_Ethernet sketch to the board.

  5. Click Tools->Serial Monitor to launch the monitor tool in a new window, which will display the output generated by the sketch.

The Arduino will boot, connect to the network, obtain an IPv4 address, display it, and then wait for an OTA firmware upload. Make a note of the IPv4 address, then close the Arduino IDE.

Configuration

To complete configuration, some additional details will be required:

  • MQTT broker - The IPv4 address of the MQTT broker which Garaduino will use.

  • BLE beacon name - The name that the BLE beacon broadcasts.

Configuration settings in Makefile:

  • ARDMK_DIR - Set this to the path of the clone of the Arduino-Makefile repository.

  • BOARD_TAG - Set this to the tag for the Arduino board being used; to obtain the list of possible tags, run make show_boards after setting ARDMK_DIR.

  • MONITOR_PORT - Set this to the name of the serial port shown in the Arduino IDE when the board is connected.

  • ARDUINO_LIBS - Confirm that the version number of arduino-timer-cpp17 matches the version which was installed.

  • ARDUINO_HOST - Set this to the IPv4 address of the Arduino board (from the bootstrap step), or hostname which maps to that address if a hostname has been configured in DNS or in the computer's hosts file.

  • ARDUINO_OTA_PASSWORD - Password chosen for the OTA upload process.

  • DEBUG - Set this to any value to produce a 'debug' build which can be monitored via the Arduino USB port.

Configuration settings in config.hpp:

  • MQTT_BROKER_NAME - Set this to the IPv4 address of the MQTT broker.

  • BLE_BEACON_NAME - Set this to the name that the BLE beacon broadcasts.

The remaining settings in config.hpp are reasonable defaults, but can be adjusted later if desired.

Build

To build the software:

$ make all

If this is successful, the final section of the output will look similar to this:

   text	   data	    bss	    dec	    hex	filename
  64708	      0	   5248	  69956	  11144	build-mkrwifi1010/garaduino.elf

If the build is not successful, correct any configuration errors and try again; if the failures are not caused by configuration errors, open an issue to report the problem.

Installation

Before installing Garaduino, follow the steps in HARDWARE to connect the sensors.

In a second window, run:

$ make monitor

This will open a monitor session displaying the output from the Arduino, in a similar fashion to the Serial Monitor tool in the Arduino IDE.

Return to the first window, and run:

$ make ota

This will attempt to connect to the Arduino over the network, upload the Garaduino software, and reboot the Arduino. If this is successful, the Serial Monitor window will show the startup output from Garaduino as it initializes its various components and connects to the network.

If the OTA upload process fails, double-check that the configuration settings are correct. Any configuration changes made in Makefile require a 'clean build' to be created:

$ make clean
$ make all

With a debug build in place and the monitor session open, test the various sensors connected to the Arduino; each sensor change will generate output in the monitor session, and in addition there shoule be regular 'Heartbeat' messages to indicate that Garaduino is running.

Use a suitable MQTT subscription tool to watch the message traffic on the MQTT broker; with that tool displaying all topics, various messages will be shown as the sensor statuses change. In addition the 'garaduino/status' topic will show 'online' and the 'garaduino/version' topic will show the version of the Garaduino software.ap

Finally, to install a non-debug build, edit Makefile again to clear any value set for DEBUG, then:

$ make clean
$ make ota

This will once again build the software and use the OTA upload process to install it. Nothing will appear in the monitor session, however, since this is a non-debug build, but the MQTT subscription tool should display messages as Garaduino restarts.

Installation is now complete; Garaduino is running on the Arduino, and can be updated over the network. Disconnect the USB cable and install the Arduino in the appropriate location.