README: add project documentation
This commit is contained in:
parent
e0e5227803
commit
f7bf415eca
121
README.md
121
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.
|
||||
|
||||
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).
|
||||
|
|
Loading…
Reference in New Issue