Skip to content

Commit

Permalink
Fix #176: add platform guid documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@terrillmoore
terrillmoore committed Jun 26, 2019
1 parent d78a0c1 commit 0dfee72
Showing 1 changed file with 145 additions and 0 deletions.
145 changes: 145 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,17 @@ _Apologies_: This document is a work in progress, and is published in this inter
- [Board-specific Classes](#board-specific-classes)
- [Class derivation](#class-derivation)
- [Platform Management](#platform-management)
- [Platform GUIDs](#platform-guids)
- [GUIDs for the Catena 461x family](#guids-for-the-catena-461x-family)
- [Catena 4610](#catena-4610)
- [Catena 4611](#catena-4611)
- [Catena 4612](#catena-4612)
- [GUIDs for the Catena 4450/4460/4470 family](#guids-for-the-catena-445044604470-family)
- [Catena 4450](#catena-4450)
- [Catena 4460](#catena-4460)
- [Catena 4470](#catena-4470)
- [GUIDs for the Catena 4801 family](#guids-for-the-catena-4801-family)
- [GUIDs for Adafruit Feather M0s](#guids-for-adafruit-feather-m0s)
- [Pollable Interface](#pollable-interface)
- [LoRaWAN Support](#lorawan-support)
- [FRAM Storage Management](#fram-storage-management)
Expand Down Expand Up @@ -121,10 +132,144 @@ The following figures gives the class derivation hierarchy for the board classes

### Platform Management

The hardware supported by this platform is generally similar. The architecture allows for the following kinds of variation (as outlined in the class hierarchy):

1. CPU differences (Cortex M0, RISC-V, etc.)
2. SOC differences (SAMD21, STM32L0, etc.)
3. PC-board differences (different sensors, power supply, capabilities)
4. Optional component population differences (pull-up resistor values, etc.)
5. Externally-connected sensors (one-wire temperature sensors, etc.)

Items 1-3 are to some degree known at compile time, based on the Catena model chosen. However, it's inconvenient to update the BSP for every possible modification, so we allow some variation at run time, guided by the contents of FRAM.

The system is identified to the software by a platform object, of type `CATENA_PLATFORM`. Several platform objects are built into the firmware image, based on the known variations for component population and external sensors. The appropriate platform object is located at boot time by the Catena Arduino Platform framework. Some values representing possibly variation are stord as `PlatformFlags` in the `CATENA_PLATFORM`. This variable is of type`PLATFORM_FLAGS`.

#### Platform GUIDs

Each `CATENA_PLATFORM` has a unique identification. This is a 128-bit binary number called a GUID (or [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)), generated by MCCI during the system design process. The platform GUIDs are defined in the header file [`Catena_Guids.h`](./src/Catena_Guids.h). For convenience, here's a table of the known GUIDs.

All of these names begin with the string `GUID_HW_`, so we omit that from the tables below.

The M101 and M102 designations are used by the [Catena-Sketches](https://github.com/mcci-catena/Catena-Sketches) family of applications to determine what external sensors are available. This lets them avoid trying to poll external hardware unless the appropriate platform configuration is set. The well known configurations are:

- **M101**: external sensors on screw terminals are contact closures, and should be totalized.
- **M102**: external sensors on screw terminals are a mixture of one-wire temperature sensors and two-wire soil temperature/humidity probes.

The designations "M103" and "M104" are reserved for use by MCCI.

For boards with FRAM, the appropriate platform GUID should be selected and programmed into FRAM using the command `system configure platformguid`, followed by the GUID value. For boards without FRAM, the library has provisions for tying the GUID to the CPU serial number. Contact MCCI for details.

The tables below were generated from `Catena_Guids.h` using a script, and then hand annotated. The script is a one-line shell command using awk:

```bash
awk '/^[/][/]/ {
s = $2; gsub(/[{}]/, "", s);
getline;
g = $2; gsub(/\(f\)$/, "", g);
gsub(/^GUID_HW_/, "", g);
printf("`%s` | `%s` |\n", g, tolower(s));
}' src/Catena_Guids.h | LC_ALL=C sort
```

#### GUIDs for the Catena 461x family

##### Catena 4610

The Catena 4610 uses a LiPo battery like traditional Feathers, and includes a BME280 temperature/pressure/humidity sensor, and a Si1133 light sensor.

Name | GUID | Description
-----|------|------------
`CATENA_4610_BASE` | `53ca094b-b888-465e-aa0e-e3064ec56d21` | Base Catena 4610, assuming no modifications or customizations.
`CATENA_4610_M101` | `6a5d8d0c-d5ae-4143-adc7-8f84ec56a867` | Catena 4610 M101, configured for power monitoring and other pulse-input applications.
`CATENA_4610_M102` | `18252b1c-3c0d-403e-8012-224d96c5af06` | Catena 4610 M102, configured for environental monitoring
`CATENA_4610_M103` | `c2cf6cf4-a4c3-4611-941f-6955ffa5bfdc` | Catena 4610 M103 -- contact MCCI
`CATENA_4610_M104` | `bfed4740-a58a-4ef6-933a-09cb22e93d00` | Catena 4610 M104 -- contact MCCI

##### Catena 4611

The 4611 uses a boost regulator that is either on or fully off, controlled by the enable pin. It's therefore a hybrid between the 4610 (which uses a battery charger switch controlled by the enable pin), and the 4612 (which instead uses the switch to jump from raw Vbat to regulated 3.3V). The 4611 is available by special order from MCCI. Generally, MCCI uses the 4612 instead.

Name | GUID | Description
-----|------|------------
`CATENA_4611_BASE` | `9bb29dca-0685-4837-8182-3dfa309d279f` | Base Catena 4611, assuming no modifications or customizations.
`CATENA_4611_M101` | `4e995471-1570-4767-adae-6657ef871bcd` | Catena 4611 M101, configured for power monitoring and other pulse-input applications.
`CATENA_4611_M102` | `964bcf91-9c45-4386-a6e7-5f2d7c3641ef` | Catena 4611 M102, configured for environmental monitoring.
`CATENA_4611_M103` | `c85b27cb-7cf9-4025-92bb-2009c08449e5` | Catena 4611 M103 -- contact MCCI
`CATENA_4611_M104` | `c22be8af-e693-4319-b243-1c2d10197973` | Catena 4611 M103 -- contact MCCI

##### Catena 4612

The 4612 runs off an unregulated battery supply, with the option of a boost regulator that can bring the system voltage up to 3.3V.

Name | GUID | Description
-----|------|------------
`CATENA_4612_BASE` | `915decfa-d156-4d4f-bac5-70e7724726d8` | Base Catena 4612, assuming no modifications or customizations.
`CATENA_4612_M101` | `d210a354-c49a-4c4f-856a-4b545dcfaa20` | Catena 4612 M101, configured for power monitoring and other pulse-input applications.
`CATENA_4612_M102` | `7fa9709d-17af-463e-ae7f-8210e49acd7a` | Catena 4612 M102, configured for environmental monitoring.
`CATENA_4612_M103` | `ff8b2ac6-75cd-4ed3-980b-50b209e64551` | Catena 4612 M103 -- contact MCCI
`CATENA_4612_M104` | `dea48489-cdac-43f4-b8ad-edb08ce21546` | Catena 4612 M103 -- contact MCCI

#### GUIDs for the Catena 4450/4460/4470 family

##### Catena 4450

The 4450 Feather Wing includes a BME280 temperature/humidity/pressure sensor, and a BH1750 lux sensor.

Name | GUID | Description
-----|------|------------
`CATENA_4450_BASE` | `60480acb-dc5d-4148-b6c9-aca13449cf1d` | Base Catena 4450, assuming no modifications or customizations.
`CATENA_4450_M101` | `82bf2661-70cb-45ae-b620-caf695478bc1` | Catena 4450 M101, configured for power monitoring and other pulse-input applications.
`CATENA_4450_M102` | `2281255e-ac5c-48cb-a263-9dc890d16638` | Catena 4450 M102, configured for environmental monitoring.
`CATENA_4450_M103` | `1fb2506f-0f2a-4310-9e6a-9bc191e0ae12` | Catena 4450 M103 -- contact MCCI
`CATENA_4450_M104` | `a731f637-e3ed-4088-a9a8-f54b6671dcf6` | Catena 4450 M103 -- contact MCCI

##### Catena 4460

The 4460 Feather Wing includes a BME680 air quality sensor, and a BH1750 lux sensor.

Name | GUID | Description
-----|------|------------
`CATENA_4460_BASE` | `3037d9be-8ebe-4ae7-970e-91915a2484f8` | Base Catena 4460, assuming no modifications or customizations.
`CATENA_4460_M101` | `31e563d1-0267-43fc-bca0-9a4cb5bfc55a` | Catena 4460 M101, configured for power monitoring and other pulse-input applications.
`CATENA_4460_M102` | `494f3c17-8ac1-4f80-8ecc-ca4dd3dccbdc` | Catena 4460 M102, configured for environmental monitoring.
`CATENA_4460_M103` | `a882186f-f4ab-4ee4-9402-7b628a76d886` | Catena 4460 M103 -- contact MCCI
`CATENA_4460_M104` | `398a9e5a-e22f-4265-9d35-bf45433ddbe3` | Catena 4460 M103 -- contact MCCI

##### Catena 4470

The 4470 Feather Wing includes a BME280 temperature/humidity/pressure sensor, a BH1750 lux sensor, and a Modbus/RS-485 interface connected to `Serial1`.

Name | GUID | Description
-----|------|------------
`CATENA_4470_BASE` | `ea8568ec-5dae-46ee-929a-a3f6b00a565e` | Base Catena 4470, assuming no modifications or customizations.
`CATENA_4470_M101` | `dd0a37a6-e469-43ec-b173-fed795129455` | Catena 4470 M101, configured for power monitoring and other pulse-input applications.

#### GUIDs for the Catena 4801 family

Name | GUID | Description
-----|------|------------
`CATENA_4801_BASE` | `10ea7e25-a4a4-45fd-8959-c04a6a5d7f95` | Base Catena 4801, assuming no modifications or customizations.

#### GUIDs for Adafruit Feather M0s

MCCI also uses this libray with Feather M0s without MCCI hardware. These GUIDs are useful in that situation.

Name | GUID | Description
-----|------|------------
`FEATHER_M0_LORA_TTNNYC` | `a67ad93c-551a-47d2-9adb-e249b4cf915a` | Feather M0 LoRa, modified per The Things Network NYC standards -- DIO1 connected to D6.
`FEATHER_M0_LORA` | `e2deccc8-55fa-4bd3-94c3-ce66bcd0baac` | Feather M0 LoRa, but DIO1 connection is not known.
`FEATHER_M0_PROTO_WINGLORA_TTNMCCI` | `3bab150f-6e32-4459-a2b6-72aced75059f` | Feather M0 Proto with a separate LoRa Feather Wing. This is sometimes known as an MCCI Catena 4420.
`FEATHER_M0_PROTO` | `f6a15678-c7f3-43f4-ac57-67ef5cf75541` | A Feather M0 Proto.
`FEATHER_M0` | `2e6dfed4-f577-47d5-9137-b3e63976ae92` | Some unspecified member of the Feather M0 family.

### Pollable Interface

*To be supplied*

### LoRaWAN Support

*To be supplied*

### FRAM Storage Management

Many MCCI Catena models include FRAM storage for keeping data across power cycles without worrying about the limited write-tolerance of EEPROM or flash. (FRAM, or ferro-electric RAM, is essentially non-volatile memory that can be freely written. Flash EPROM and EEPROM can be written, but tend to have non-local error properties and limited write durability. They are good for storing code, but troublesome for storing counters, because a location must be updated each time a counter is written.)
Expand Down

0 comments on commit 0dfee72

Please sign in to comment.