diff options
authorKing Kévin <kingkevin@cuvoodoo.info>2020-06-10 18:09:15 +0200
committerKing Kévin <kingkevin@cuvoodoo.info>2020-06-10 18:09:15 +0200
commitf7bf415eca3ca7ff1174c89213d47ac9439bb311 (patch)
parente0e5227803cb1bdf510eeaad540f6efc1dc098da (diff)
README: add project documentationyougotparcel
1 files changed, 90 insertions, 35 deletions
diff --git a/README.md b/README.md
index f37860c..76464a3 100644
--- a/README.md
+++ b/README.md
@@ -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.
@@ -6,50 +6,97 @@ project
-*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.
-*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.
-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.
-Connect the peripherals the following way (STM32F10X signal; STM32F10X pin; peripheral pin; peripheral signal; comment):
-- *list board to peripheral pin connections*
-All pins are configured using `define`s in the corresponding source code.
+connect the peripherals the following way (STM32F10X signal; STM32F10X pin; peripheral pin; peripheral signal; comment).
+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;
+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.
@@ -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.
@@ -99,4 +154,4 @@ To start the debugging session run `rake debug`.
-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).