Welcome to NeoBee’s documentation!¶

Getting started¶

First of course you need to get the hardware part prepared. If not, first go to the hardware section.

Currently the documenation only takes linux into accounte. But if you are familiar with windows, most things should work quite similar.

Flashing the Firmware¶

First you need to flash the neobee firmware to your wemos. Every version of the firmware comes as a debug and a production version. You can download the firmware from github.

Or, if you prefer to use curl:

curl -L https://github.com/FirstKlaas/neobee/raw/master/neobee_firmware/firmware/neobee_wemos_latest-debug.bin --output neobee_latest.bin

Although not really necessary, I emphasize to do the installation of the library in a virtual environment. If you do no not how to setup a virtual environment, do q quick search on the internet. There are dozens of HOWTOs.

In a nutshell is is something like this:

mkdir neobee
cd neobee
python3 -m venv venv
source ./venv/bin/activate

Now you can use pip to install esptool and the neobee library and tools. I normally install the wheel library first.

pip install wheel
pip install esptool
pip install neobee

That’s everything you need.

Now you can flash the firmware you just downloaded:

esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 ../neobee_latest.bin

esptool.py v2.8
Serial port /dev/ttyUSB0
Connecting....
Detecting chip type... ESP8266
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 84:f3:eb:90:6d:c2
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Changed.
Configuring flash size...
Auto-detected Flash size: 4MB
Compressed 294880 bytes to 211650...
Wrote 294880 bytes (211650 compressed) at 0x00000000 in 4.8 seconds (effective 495.9 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...

Of course you have to adopt the device to whatever is the right one for you.

If everything worked fine. The LED of yout NeoBee Board should be on. Also a new wifi network shows up NeoBee. Congratulations!!! Your board is working. Maybe a good moment for a cup of tea.

Checking the log messags with a teminal¶

If you flashed the debug version of the fimware, you can watch the log messages with a terminal app.

Here I use screen to connect to the board. Of course this works only, if the board is connected to your computer via an usb cable.

In a linux terminal type in:

screen /dev/ttyUSB0 9600

The 9600 is important, because the speed is part of the firmware and cannot be changed (unless you chang the source code).

Here’s a short video on how this will look like.After starting screen you need to press the reset button of your board.

Configuring the board¶

Next step is to configure the board. If you have started with a fresh installation of the firmware, the controller is not configured. For example the controller does not know which wifi networt to connect to.

Therefore the controller automatically boots into AP (Access Point) mode. You should find a new WiFi network called “NeoBee” you can connect to without the need of any credentials.

At least for the configuration of the wifi network, the computer needs to be connected to this neobee hotspot.

Note

Of course the controller does not act as a router or dns server. So beware of the fact that as long as you are connected to the controller you cannot access the internet or other lokal ressources.

The easiest way is to download the current configuration, which is of course empty, but serves as a template. When the board acts as an AP, the IP for the board is 192.168.4.1.

Note

Connect to the network called NeoBee!

To download the configuration, type the following command:

neobee 192.168.4.1 -o configuration.json

The generated file should look like this (the firmware version may differ):

{
"firmware_version": "0.1.1",
"device_name": null,
"mac_address": "84:f3:eb:90:6d:c2",
"ssid": null,
"password": null,
"deep_sleep_seconds": 30,
"scale_offset": null,
"scale_factor": null,
"mqtt_host": null,
"mqtt_port": null,
"mqtt_login": null,
"mqtt_password": null
}

Leave the firmware_version and the mac_adress entry as they are and adopt all other setting to your needs. Most probably, you will not know the correct values for the scale_factor and the scale_offset. We will determine these values in the in the taring and calibrating the scale tutorial.

After saving out your changes, you can know easily configure your board using the configuration file.

Note

Delete the line you don’t want to change or have no value bevor writing them back.

A configuration file to just set the name and the wifi credentials woul look like:

{
    "firmware_version": "0.0.1",
    "device_name": "Neo1",
    "ssid": "myssid",
    "password": "mypassword"
}

To then configure the board just type the following command:

neobee 192.168.4.1 -i configuration.json --save --reset

The board will reset and connect to the configured wifi network. If the board is not able to connect to the wifi network, it will again setup an access point.

The Hardware and the Circuit¶

THe following picture shows the circuit for the NeoBee hive logger. I used two dallas 18b20 temperature sensors. One sensore to be used inside of the hive and one sensore to be used outside of the hive.

The load cell is connected via the HX711 analog digital converter. The status led gives some visual feedback in case of an error or to signal, that we are in command mode.

When the command button is pressed during boot, the board will enter the command mode.

To use the deep sleep funcinality, the pin D0 has to be connected to GND. But if done so, it is impossible to upload new firmware. Therefore I integrated a jumper. So remove the jumper before flashing and put it on afterwards.

Setting up the NeoBee Python Library¶

Installing the NeoBee library is a piece of cake, as it is hosted on PyPi. Although you can install globally (as root) or in user space, I recommend you to use a virtual environment. Follow along the next steps and you’re good to go.

Open a terminal and type:

mkdir neobee
cd neobee
python3 -m venv venv
source ./venv/bin/activate

Now you can use pip to install the neobee library. I normally install the wheel library first.

pip install --upgrade pip
pip install --upgrade wheel
pip install --upgrade neobee

That’s everything you need.

This installs a neobee programm to configure youre device. Try the following:

neobee --help

You should get something like:

usage: neobee [-h] [-v] [--reset] [--erase] [-s] [-n NAME] [--ssid SSID]
            [--password PASSWORD] [--mqtt-host MQTT_HOST]
            [--mqtt-port MQTT_PORT] [--mqtt-login MQTT_LOGIN]
            [--mqtt-password MQTT_PASSWORD] [--scale-offset SCALE_OFFSET]
            [--scale-factor SCALE_FACTOR] [-o OUT_FILE] [-i IN_FILE]
            host

positional arguments:
host                  The NeoBee host, to connect to.

optional arguments:
-h, --help                      Show this help message and exit
-v, --verbose                   Show some more output.
--reset                         Reset the board
--erase                         Erase the configuration data
-s, --save                      Save configuration data
-n NAME, --name NAME            The name of the neobee board
--ssid SSID                     The wifi network to connect to
--password PASSWORD             The wifi password
--mqtt-host MQTT_HOST           The mqtt host
--mqtt-port MQTT_PORT           The mqtt port
--mqtt-login MQTT_LOGIN         The mqtt login
--mqtt-password MQTT_PASSWORD   The mqtt password
--scale-offset SCALE_OFFSET     The scale offset
--scale-factor SCALE_FACTOR     The scale factor
-o OUT_FILE, --out-file OUT_FILE    Writing the settings to
-i IN_FILE, --in-file IN_FILE   Reading the settings from

NeoBee Command¶

After installing the NeoBee python library, you can use the neobee tool to manage the controller. Under linux you can call the neobee command directly. On windows you need to use it like this:

python -m neobee.neobee

The neobee command is the swiss army knife tool to manage your device. In this chapter we will have look at all the different options.

Every command needs the IP of the board. In this documentation I will use 192.168.178.30. Of course you have to adopt this to the correct IP of your board.

Note

The neobee programm works only, if the controller is in command mode.

Display the help message¶

To display the integrated help message just call:

(venv) $ neobee --help

Print the current configuration¶

To display the current configuration simply call:

(venv) $ neobee --dump 192.168.178.30

Export the current configuration¶

The following command exports the current configuration to the specified file. If the file already exists, it will be overwritten.

(venv) $ neobee -o configuration.json 192.168.178.30

Entering the Command Mode¶

Connect the board via USB to your computer.
Press and hold the CMB Button
Push the RESET Button. After a couple of seconds, the status led should be constantly on, telling us, we are in command mode.

Time for a Wohoo.

Taring and Calibrating the Scale¶

The load cell is connected via a HX711 analog-to-digital converter. It converts the weigth to an 24 bit value. Bevor we can use it as an scale, we have to calibrate the sensor values.

First we need the offste. The offset is the value, we measure, wenn the scale is empty. This is also known as taring. Make shure, you know how to enter the command mode.

Currently configuration is done via python. If you haven’t set up the python environment, please read the instructions on Setting up the NeoBee Python Library.

To tare the weight, follow the steps:

Connect the board via USB to your computer.
Boot the board into command mode.
Press and hold the CMB Button
Now the python part

Commands¶

The NeoBee board defines its own tcp based communication protocol based on tcp/ip. The board acts as a server. It supports all commands needed to configure the board as well as read the sensore data.

Paket structure¶

All pakets have a fixed size of 32 bytes. The first byte of a request packet contains the commande code. The second byte defines the method. For details read the related command documentation. The rest of the bytes contain the data.

Request Method¶

The two least bits of the second byte define the request method. Following methods are possible.

0	NONE	Method not used.
1	GET	The method to read values
2	PUT	Method used to write/change values
3	DELETE	Method used to delete/reset values

[01] Name¶

Managing the human readable name of the board. Supported methods are GET, PUT, DELETE. The maximum length of the name is 30 bytes. Because there is no way to define the encoding, the bytes are copied directly. An ASCII encoding is highly emphasized.

Request¶

Byte	Description
00	Command byte. Always 2
01	Supported methods (`GET` / `PUT` / `DELETE`)
02-29	Name in case of method `PUT`. Zeroed for the other methods.

Response¶

Byte	Description
00	Command byte. Always 2
01	Response Status
02-29	Name in case of method `GET`. Zeroed for the other methods.

[04] Reset Settings¶

Clears all settings. After rebooting the system, the board will automatically go access point mode, as we don’t have any wifi credentials to connect to.

Request¶

Byte	Description
00	Command byte. Always 4
01	Method. Always `PUT`
02-29	0 [unused]

Response¶

Byte	Description
00	Command byte. Always 4
01	Response Status
02-29	0 [unused]

[05] Save Settings¶

Saves the settings to the EEPROM.

Request¶

Byte	Description
00	Command byte. Always 5
01	Method. Always `PUT`
02-29	0 [unused]

Response¶

Byte	Description
00	Command byte. Always 5
01	Response Status
02-29	0 [unused]

[06] Erase Settings¶

Fills the configuration space in EEPROM with zeros.

Byte	Description
00	Command byte. Always 6
01	Request Modifier. Always 0
02-29	0 [unused]

[07] Reset Board¶

Rests the board. To be more precise, restarts the board. After a reset, all changes made to the board will take effect.

Byte	Description
00	Command byte. Always 7
01	Request Modifier. Always 0
02-29	0 [unused]

[10] Get Scale Offset¶

Returns the current offset of the scale. The offset defines the 0 level of the weight.

Byte	Description
00	Command byte. Always 10
01	Request Modifier. Always 0
02-29	0 [unused]

[11] Set Scale Offset¶

Sets the current offset of the scale. The offset defines the 0 level of the weight.

Byte	Description
00	Command byte. Always 11
01	Request Modifier. Always 0
02-05	F100 value for the offset
06-29	0 [unused]

[12] Get Scale Factor¶

Returns the current factor of the scale. The factor converts the internal units into the external values. Check out the calibration page for more information.

Byte	Description
00	Command byte. Always 12
01	Request Modifier. Always 0
02-29	0 [unused]

[13] Set Scale Factor¶

Sets the current factor of the scale. Check out the calibration page for more information.

Byte	Description
00	Command byte. Always 13
01	Request Modifier. Always 0
02-05	F100 value for the factor
06-29	0 [unused]

[20] Get SSID¶

Returns the wifi networkname name (the ssid) to connect to. If no ssid was configured. Returns a NOT_FOUND status.

Request¶

Byte	Description
00	Command byte. Always 20
01	Request Modifier. Always 0
02-29	0 [unused]

Response¶

Byte	Description
00	Command byte. Always 20
01	Status. `OK` if name was set, `NOT FOUND` else.
02-29	The ssid. Unused bytes are 0

[21] Set SSID¶

Set the ssid to connect to.

Request¶

Byte	Description
00	Command byte. Always 21
01	Request Modifier. Always 0
02-29	The name of the ssid. Unused bytes should be set to 0

[22] Clear SSID¶

Clears the ssid to connect to. When no ssid is set, the board will automatically go into AP mode after reboot. The preferred way to force AP mode is to do a Set Wifi Active(False) request.

Request¶

Byte	Description
00	Command byte. Always 22
01	Request Modifier. Always 0
02-29	0 [unused]

[23] Get Password¶

Gets the currently configured wifi password.

[24] Set Password¶

Sets the wifi password.

[25] Clear password (deprecated)¶

Clears the wifi password. This command is deprecated and will be removed in future releases. Please use set password, where the first byte of the name is 0.

[26] Enable or disable wifi¶

Enables or disables the wifi connection. If diabled, the board will boot into AP mode after reboot. If enabled, it will try to connect to the configured wifi network. If no network is configured, the board will also go into AP mode

[27] Get wifi flags (deprecated)¶

Gets the wifi flags

F100 Values¶

All floating point values are encoded with a precision of to digits as int32 values. What exactly does this mean?

Let’s start with an example:¶

The current measured weight is 22.7576. The transmitted value is calculated like this: int(22.7576 * 100.0 + 0.5) which gives us a value of 2276. The value is then packet in four bytes. The first two bytes represent then HighWord of the value and the next two bytes represent the LowWord of the value. Both words are packed in HighByte / LowByte.

So the value 22.7576 would be converted to 2276 and then packed as: TODO

`HighWord(val)`	`(val >> 16) & 0xFFFF`
`LowWord(val)`	`val & 0xFFFF`
`HighByte(val)`	`(val >> 8) & 0xFF`
`LowByte(val)`	`val & 0xFF`

NeoBeeShell¶

NeoBeeShell is the main class to interact with the controller programmatically. The purpose if the library is to read and write the configuration settings. The library uses a tcp communication. So to use the library, you do not need the serial line of the usb cable. The benfit of this approach is, that you are able to accessthe board remotely as long as you are in the same network.

Because a tcp socket is used, it is important to close the socket at the end. The NeoShell class implements pythons context protocol. Therefore you can use it in a with clause, which garantuees to close the socket. No need to open and close the socket. Thats all managed for you in the background. It makes code safer and more human readable.

Here’s an example:

with NeoBeeShell(host="192.168.178.80") as s:
    name = s.name
    s.wifi_password = "mysecret"
    s.save_configuration()

API Documentation¶

class neobee.shell.NeoBeeShell(host='192.168.4.1', port=8888)¶

The NeoBeeShell is the main class to configure the controller programmatically. The class implements pythons context protocol. To use this class, you have to be in the same network as the controller. When the controller acts as an access point, connect to the controller before using the class.

When using with the with clause, the class connects before executing the statements and disconnects at the end. Even if an exception occurs. This is the preferred way to use the class.

Parameters

host (str, optional) – The IP of the controller. Defaults to 192.168.4.1
port (int) – The port to connect to. Defaults to 8888

calibrate(ref_weight: int, count: int)¶

Calibrates the scale. Before calibrating the scale, be sure, to tare the scale correctly.

To calibrate the weight, a reference weight is needed. And the value you provide determines the unit to be used.

Example:

Put a weight of 1 kilogramm onto the scale. If you now call this method with a ref_weight of 1, all measurements are done in kilogramm. If you call this method with a value of 1000, all measurements are done in gramm.

connect()¶

Connects to the controller. If a connection already has been established, an AlreadyConnectedError is raised.

The preferred way to use this class is in a with statement, which eliminates the need to connect or disconnect explicitly.

property connected¶: Boolean flag indicating if the controller is connected or not.

disconnect()¶: Disconnects from the controller. If no connection has been established, an NotConnectedError is raised.

erase_settings()¶: Removes the stored settings from flash memory. After a reboot, the board acts as a AP again.

property info¶: Returns a NeoBeeInfo object, which contains all the current settings.

property mac_address¶: Returns a MacAddress object with the mac address of the board.

property name¶

String property for the name of the board. The length of the name is limited to 20 and is expected to be in ascii encoded.

If a name longer then 20 characters is provided, a DataError is raised.

save_settings()¶: Stores the settings to the flash memory.

property scale_factor¶: Float property for the scale factor.

property scale_offset¶: Float property for the offset of the scale.

property ssid¶: String property for the ssid of the wifi network.

tare(nr_times: int)¶

Command to trigger the taring.

Taring is the process to determine the 0 value of the scale. So, before triggering this command, empty the scale.

nr_times specifies the number of measurements excecuted to calculate the tare as an average of the measured values.

property temperature¶: Reads the temperature of both sensors. Returns the temperature as a float value in celsius degree.

property version¶: Returns the version of the firmware as a tuple (MAJOR, MINOR, BUILD).

property wifi_password¶: String property for the wifi_password.

MQTT¶

To setup mqtt broadcasting the controller needs to be connected to a wifi network in order to find the mqtt borker. Additionally you need to configure at least the host and the port of the mqtt broker. If needed you also have to provide the credentials.

The easiest way is to use the neobee command that is available after you installed the library. The process of configuration is explain in Configuring the board.

Now delete all rows in the config file beside the mqtt rows and the firmware version. Now fill in the apropiatecvalues. If you don’t need credentials simply drop those lines too.

{
"firmware_version": "0.1.1",
"mqtt_host": "broker.hivemq.com",
"mqtt_port": 1883
}

Now load back the configuration to the board and don’t forget to save the configuration. Othwerwise it will be lost after a reboot.

neobee 192.168.4.1 -i configuration.json --save --reset

The Payload¶

Every mqtt message coems with a payload. The payload contains the data. For neobee all informations are packed in one payload. This ensures, that you can be sure, that all data belongs to the same timestamp. Also the traffic is reduced. On the other hand, you have split the bytes to get the detailed data.

Every time the controller publishes its information, the data is packed into an 18 byte long payload.

Byte 0-5: contain the 6 bytes of the controllers MAC address
Byte 6-9: contain the weight as a f100 value
Byte 10-13: contain the temperature inside as a f100 value
Byte 14-17: contain the temperature outside as a f100 value

Topics¶

When the board connects to the mqtt server it publishes a messagewith the topic /neobee/hive/connect. The payload contains the MAC address [6 bytes], the IP [4 bytes] and the name [20 bytes] of the board.

Everytime a measurement is triggered, a message with the topic /neobee/hive/rawdata is send. The payload contains the data as desribed above.

Welcome to NeoBee’s documentation!¶

Getting started¶

Flashing the Firmware¶

Checking the log messags with a teminal¶

Configuring the board¶

The Hardware and the Circuit¶

Setting up the NeoBee Python Library¶

NeoBee Command¶

Display the help message¶

Print the current configuration¶

Export the current configuration¶

Entering the Command Mode¶

Taring and Calibrating the Scale¶

Commands¶

Paket structure¶

Request Method¶

[01] Name¶

Request¶

Response¶

[04] Reset Settings¶

Request¶

Response¶

[05] Save Settings¶

Request¶

Response¶

[06] Erase Settings¶

[07] Reset Board¶

[10] Get Scale Offset¶

[11] Set Scale Offset¶

[12] Get Scale Factor¶

[13] Set Scale Factor¶

[20] Get SSID¶

Request¶

Response¶

[21] Set SSID¶

Request¶

[22] Clear SSID¶

Request¶

[23] Get Password¶

[24] Set Password¶

[25] Clear password (deprecated)¶

[26] Enable or disable wifi¶

[27] Get wifi flags (deprecated)¶

F100 Values¶

Let’s start with an example:¶

NeoBeeShell¶

API Documentation¶

MQTT¶

The Payload¶

Topics¶

Indices and tables¶