README: add project documentation

This commit is contained in:
King Kévin 2020-06-10 18:09:15 +02:00
parent e0e5227803
commit f7bf415eca
1 changed files with 88 additions and 33 deletions

121
README.md
View File

@ -1,4 +1,4 @@
This firmware template is designed for development boards based around [STM32 F1 series micro-controller](http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1031).
YouGotParcel is a pair of devices that remotely tells if a parcel has been put in the post box.
project
=======
@ -6,50 +6,97 @@ project
summary
-------
*describe project purpose*
one of the device goes into the post box.
using switches it can detect when the door of lid have been opened.
it then transmits the activity to the other device over radio.
the second device receives the activity messages, and shows the status of the post box using LEDs.
if the lid is opened, the green LED will light up, indicating a package is present in the post box.
if the door is opened, the red LED will light up, indicating the post box have been emptied.
if no indication has been received (> 1h), both LEDs will switch off.
technology
----------
*described electronic details*
to transmit the status, the LoRa radio protocol is used.
Semtech SX1728 modules for the 433 MHz band (420 - 450 MHz) are used, but any SX172x module for any band (allowed by the local regulation) can be used.
it does not use LoRaWAN (which requires an infrastructure and the right band support), but just LoRa directly between the two modules.
each part has one of the LoRa modules.
one will be used to transmit (the one in the post box), while the other while be used to receive (at the remote location).
the modules are the same, and can be used to transmit and receive.
LoRa is used because, as the name says, it can transmit data over a long range.
this is at the price of baud rate, but since we only need to transmit if lid or door has been opened (e.g. 1 bit), this is sufficient.
the module is configured for most resilient transmission:
- lowest bandwidth: 62.5 kHz (minimum when using a XTAL clock source)
- largest spreading factor: 12
- largest coding rate: 4/8
- explicit header: providing length
- CRC checksum: providing forward error correction
- use power amplifier: providing a 20 dBm signal output
- no output power reduction: to use the maximum 20 dBm signal output
- maximum gain amplifier: 1
- least active frequency: 447.681 MHz (found by scanning the frequency range using the 'scan' action in the receiver menu and using selecting the frequency with the lowest RSSI).
using these parameters it take almost 2 seconds to transmit 1 byte of payload.
my flat is only ~ 30 m direct line from the post box.
LoRa claims to be able to transmit up to 5-15 km.
but the transmitter with be in a post box made of 0.5 mm metal (e.g. almost a faraday cage), and there are several concrete walls in between.
in the end, the transmission is reliable enough and 19/20 packets are received.
the post box unit will transmit as soon as the lid or door are opened.
it will also transmit the last data every 15 minutes.
this will allow the receiver to be restarted and get the status even without activity.
this also allows to recover from lost packet transmissions.
the receiver device requires a permanent power source (e.g. a USB power port) since it continuously listens to incoming data.
is also allow to have the LED constantly on.
the transmitted device is battery operated because no power source is available in the post box.
to save power, the transmitter (MCU and radio) are put in sleep mode unless data is transmitted.
a LiPo battery (with embedded protection) is directly connected to the USB input.
the 3.6-4.2 V is sufficient to provide the 3.3 V (using an LDO) required by MCU and radio.
during transmission, the transmitter uses 62 mA, lasting 2 seconds.
during sleep, the transmitter uses 0.3 mA.
thus, the device uses (2 * 62 + 0.3 * (15 * 60 - 2)) / (15 * 60) = 0.44 mA on average.
using a 100 mAh battery, this should last for (1000 / 0.44) / 24 = 94 days.
since I go at least once a week to the post box, and can swap the battery, this is plenty sufficient.
board
=====
The current implementation uses a [core board](https://wiki.cuvoodoo.info/doku.php?id=stm32f1xx#core_board).
The underlying template also supports following board:
- [Maple Mini](http://leaflabs.com/docs/hardware/maple-mini.html), based on a STM32F103CBT6
- [System Board](https://wiki.cuvoodoo.info/doku.php?id=stm32f1xx#system_board), based on a STM32F103C8T6
- [blue pill](https://wiki.cuvoodoo.info/doku.php?id=stm32f1xx#blue_pill), based on a STM32F103C8T6
- [black pill](https://wiki.cuvoodoo.info/doku.php?id=stm32f1xx#black_pill), based on a STM32F103C8T6
- [core board](https://wiki.cuvoodoo.info/doku.php?id=stm32f1xx#core_board), based on a STM32F103C8T6
- [ST-LINK V2 mini](https://wiki.cuvoodoo.info/doku.php?id=jtag#mini_st-link_v2), a ST-LINK/V2 clone based on a STM32F101C8T6
- [USB-Blaster](https://wiki.cuvoodoo.info/doku.php?id=jtag#armjishu_usb-blaster), an Altera USB-Blaster clone based on a STM32F101C8T6
**Which board is used is defined in the Makefile**.
This is required to map the user LED and button provided on the board
The ST-LINK V2 mini clone has SWD test points on the board.
Because read protection is enabled, you will first need to remove the protection to be able to flash the firmware.
To remove the read protection (and erase flash), run `rake remove_protection` while a SWD adapter is connected.
The Altera USB-Blaster clone has a pin header for SWD and UART1 on the board.
SWD is disabled in the main firmware, and it has read protection.
To be able to flash using SWD (or the serial port), the BOOT0 pin must be set to 1 to boot the system memory install of the flash memory.
To set BOOT0 to 1, apply 3.3 V on R11, between the resistor and the reference designator, when powering the device.
The red LED should stay off while the green LED is on.
Now you can remove the read protection (and erase flash), run `rake remove_protection` while a SWD adapter is connected.
the current implementation uses a [black pill](https://wiki.cuvoodoo.info/doku.php?id=stm32f1xx#black_pill) development board, based on a STM32F103C8T6.
this board includes an 32.768 kHz oscillator, used for the RTC in the MCU to periodically wake up.
connections
===========
Connect the peripherals the following way (STM32F10X signal; STM32F10X pin; peripheral pin; peripheral signal; comment):
connect the peripherals the following way (STM32F10X signal; STM32F10X pin; peripheral pin; peripheral signal; comment).
- *list board to peripheral pin connections*
common to both devices:
- SPI2_NSS; PB12; SX1728 module; NSS;
- SPI2_SCK; PB13; SX1728 module; SLCK;
- SPI2_MISO; PB14; SX1728 module; MISO;
- SPI2_MOSI; PB15; SX1728 module; MOSI;
- GPIO; PB6; SX1728 module; DIO0; used as SX1728 IRQ output
- GPIO; PB7; SX1728 module; REST;
- GND; GND; SX1728 module; GND;
- 3V3; 3V3; SX1728 module; VCC;
All pins are configured using `define`s in the corresponding source code.
on the transmitter device:
- GPIO; PB8; board; GND; use a jumper. this is used to differentiate the transmitter from the receiver
- GPIO; PB10; lid button; common; place button on post box lid to detect when it has been opened
- GPIO; PB1; lid button; normally open; don't use the normally closed pin since the lid might not be able to close again is the parcel does not fit in the box
- GPIO; PA7; door button; common; place button so it gets pressed when the door is closed
- GPIO; PB0; door button; normally open; can also be placed on the normally closed pin since the door will be opened and closed when emptying it.
on the receiver side:
- GPIO; PB10; green LED; anode; used to provide 3.3V
- GPIO; PB1; green LED; cathode; with inline 1 kO resistor. used to indicate when the lid of the post box has been opened (e.g. a letter/parcel has arrived)
- GPIO; PA7; red LED; anode; used to provide 3.3V
- GPIO; PB0; red LED; cathode; with inline 1 kO resistor. used to indicate when the door of the post box has been opened (e.g. the box has been emptied)
all pins are configured using `define`s in the corresponding source code.
code
====
@ -83,13 +130,21 @@ It is up to the application to advertise USB DFU support (i.e. as does the provi
The `bootlaoder` image will be flashed using SWD (Serial Wire Debug).
For that you need an SWD adapter.
The `Makefile` uses a Black Magic Probe (per default), or a ST-Link V2 along OpenOCD software.
The `Makefile` uses a ST-Link V2 along OpenOCD software.
To flash the `booltoader` using SWD run `rake flash_booloader`.
Once the `bootloader` is flashed it is possible to flash the `application` over USB using the DFU protocol by running `rake flash`.
To force the bootloader to start the DFU mode press the user button or short a pin, depending on the board.
It is also possible to flash the `application` image using SWD by running `rake flash_application`.
Once the transmitter firmware has been flash over DFU, it is recommended to flash it over SWD using `rake flash_application`.
This is because the transmitter does not provide present itself as USB device, so to save energy.
Also, since the transmitter goes to sleep after a couple of second, it is recommended to flash it just after reset.
Alternatively, short BOOT1 to 3.3V and reset the device.
This will force the USB DFU bootloader, and also to flash using DFU.
The firmware is the same for transmitter and receiver.
debug
-----
@ -99,4 +154,4 @@ To start the debugging session run `rake debug`.
USB
---
The firmware offers serial communication over USART1 and USB (using the CDC ACM device class).
The firmware offers serial communication over USART1 (transmitter and receiver) and USB (only receiver) (using the CDC ACM device class).