ich777/IronOS
1
0
Fork 0
mirror of https://github.com/Ralim/IronOS.git synced 2025-07-23 12:23:06 +02:00
Code Issues Packages Projects Releases Wiki Activity

Start docs on BLE (#1763)

Browse Source 
* docs on BLE

* Tip shorted notes
This commit is contained in:
Ben V. Brown
2023-08-01 10:39:29 +10:00
committed by GitHub
parent bd9c63f55d
commit 584b3826c3
2 changed files with 111 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
Documentation/Bluetooth.md Normal file
View File

@@ -0,0 +1,99 @@
# Bluetooth Low Energy
The Pinecilv2 has hardware support for Bluetooth Low Energy (BLE). This protocol allows reading and writing of parameters to the Pinecil during runtime.
The BLE interface advertises three services, these provide access to live telemetry as well as the ability to read/write settings.
These are outlined in more detail below.
Pinecil devices advertise themselves on BLE as `Pinecil-XXXXXXX`.
They also include the UUID `9eae1000-9d0d-48c5-AA55-33e27f9bc533` in the advertisement packet to allow for filtering.
Unless otherwise noted, all data is sent and received as Little-Endian.
As of the time of writing this, notifications are not fully implemented so data will need to be polled. Notification/Indication support will come when there is time to implement it.
## Using the BLE Interface
It is advised to follow the below points when first implementing a BLE integration. Of course once the integration is working feel free to deviate from these. These are just _suggested_ ideas to help kickstart.
1. When filtering for devices, its preferable to filter by the UUID `9eae1000-9d0d-48c5-AA55-33e27f9bc533`, rather than by the device name if possible.
2. Upon first collection check if the three expected services exist; if they don't the user may have selected an incorrect device.
3. It's best to read the live bulk endpoint over the live service when its easy to do so (one read vs ~15).
1. However if you are just updating one or two line items it may be more efficient to just read these on the live service.
2. Feel free to test both and decide.
4. When reading settings from the device; the association of number <-> setting is fixed, but you may see settings you don't yet know about, make sure you can handle these.
5. You probably don't want to show unknown setting's to the user though.
6. Read the device firmware revision and ensure you can decode it. If BLE is revised it may be essential for handling versions cleanly.
7. It's advisable to keep an eye on the IronOS repository or at least setup the Github watch for release notifications.
1. Future releases may revise some BLE aspects or add new settings for example.
## Services
Below is a description of each service. Note that the exact settings are not listed for brevity; it's best to refer to [the uuid lists](https://github.com/Ralim/IronOS/blob/dev/source/Core/BSP/Pinecilv2/ble_characteristics.h) and the [handlers](https://github.com/Ralim/IronOS/blob/dev/source/Core/BSP/Pinecilv2/ble_handlers.cpp) alongside this.
### Live
`UUID: d85ef000-168e-4a71-AA55-33e27f9bc533`
The live services has one characteristic per reading. The readings (in order) are:
When implementing these; the ones that are not obvious are generally found in the debugging menu. Values are encoded as an unsigned 32 bit number for all results.
1. Live temperature (In C)
2. Live set point
3. DC input voltage
4. Handle temperature (In C)
5. Power level
6. Power source
7. Tip resistance
8. uptime
9. Time of last movement
10. Maximum temperature settable
11. Raw tip reading
12. Hall sensor
13. Operating mode
14. Estimated wattage
### Settings
`UUID: f6d80000-5a10-4eba-AA55-33e27f9bc533`
The settings service has two special entries; for saving and resetting settings.
Otherwise all settings are enumerated using UUID's of the format : `f6d7ZZZZ-5a10-4eba-AA55-33e27f9bc533))` where `ZZZZ` is the setting number as matched from [Settings.h](https://github.com/Ralim/IronOS/blob/dev/source/Core/Inc/Settings.h#L16).
All data is read and written in fixed unsigned 16 bit numbers.
#### Settings save
To save the settings write a `0x0001` to `f6d7FFFF-5a10-4eba-AA55-33e27f9bc533`.
Its advised to not save settings on each change but instead to give the user a save button _or_ save after a timeout. This is just to reduce write cycles on the internal flash.
#### Settings reset
To reset all settings to defaults; write a `0x0001` to `f6d7FFFE-5a10-4eba-AA55-33e27f9bc533`.
This will reset settings immediately.
### Bulk
`UUID: 9eae1000-9d0d-48c5-AA55-33e27f9bc533`
The bulk endpoint is where extra data is located with varying read sizes.
#### Live data
The bulk live data endpoint provides all of the data provided in the live endpoint, as one large single-read binary blob. This is designed for applications that are showing large amounts of data as this is more efficient for reading.
#### Accelerometer Name
_Not yet implemented_
#### Build ID
This encodes the current build ID to allow viewing and handling when the BLE format changes.
#### Device Serial Number
This is generally the device CPU serial number. For most devices this can be used as an ID. On PinecilV2 its the MAC address.
#### Device Unique ID
This is only relevant on the PinecilV2. This is a random ID that is burned in at the factory. This is used by the online authenticity checker tool.

12
Documentation/Troubleshooting.md
View File

@@ -14,6 +14,18 @@ But it is helpful to do some basic diagnostics first just in case the issue is e
The **VAST** majority of issues are poor soldering or cold solder joints.
If you can open up your iron, give it a good look at all the connection points, and use another iron to reflow any suspicious ones, this can fix most issues.
## Tip Shorted warning
If you are powering up a device that supports tip resistance detection (TS101 and Pinecilv2 as of present), the firmware checks the readings of the raw tip resistance and sorts these into three "bins". `8 ohm tips`, `6.2 ohm tips` and `tip-shorted`. The tip resistance is used when negotiating USB-PD and in thermal calculations.
The `tip-shorted` option is selected if your tip is measured to be abnormally small. This could indicate a failed driver mosfet or a failed tip.
When this warning is shown; heating will be disabled to protect from damage. As trying to heat a shorted tip can damage the iron itself.
It is best to take out your tip and manually measure and verify the tip's resistance. It should be 6-8 ohms (depending on tip type). When measuring resistances this small some multimeters can struggle. If you have access to a current limited bench power supply, you can try doing a 4 wire measurement by measuring the voltage drop on the tip while applying a known current. `(R=V/I)`.
If the tip measures correctly you may have a damaged driver mosfet; it would be ideal to open your iron and test the mosfet is operating correctly.
If after both of these checks everything looks as expected, feel free to open a discussion on IronOS to talk about the issue (Or for Pinecil the community chat can be a much faster response).
## High tip temp reading when the tip is cool
If you are finding the tip is reading high; the first fields to check in the Debug menu are `RTip` and `CHan`.