To fix this, I had to:

1.  Figure out the security type of the two networks.

Connect to each network, then use airport to get the security type. Note it

/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -I

For me, eduroam lists ft-wpa2 and IoT_IRL lists wpa3-sae.

1.  Remove and re-add them to en0 at different priority levels.

Now remove them both and add them back at different priorities; using 1 for the higher and 3 for the lower priority.  Note the security setting types, network name, and priority level from above here:

networksetup -removepreferredwirelessnetwork en0 eduroam
networksetup -removepreferredwirelessnetwork en0 IoT_IRL
networksetup -addpreferredwirelessnetworkatindex en0 IoT_IRL 1 wpa3-sae
networksetup -addpreferredwirelessnetworkatindex en0 eduroam 3 ft-wpa2

I was finally able to get it to work by:

(1) exporting a full resolution Apple ProRes 4444 file from After Effects.

(2) Use the Rotato tool to convert it:

Alpha channel tool: Create transparent videos for all browsers | Rotato

Transparent videos can be confusing, so we made a 1-click, privacy-first, free tool to create videos with transparency that work in all browsers.

Rotato

(3) upload both, add your video tag, and modify it via html (there is likely an edit as html button on your block element) so that it looks like the following:

<figure class="wp-block-video" style="margin-right:0;margin-left:0">
<video autoplay loop muted playsinline preload="auto" id="customedited">

<source src="http://principledinterfaces.com/wp-content/uploads/sites/5/2024/04/vid-safari.mp4" type='video/mp4; codecs="hvc1"'>

<source src="http://principledinterfaces.com/wp-content/uploads/sites/5/2024/03/vid-chrome.webm" type='video/webm'>

</video></figure>

It requires all of the attributes autoplay loop muted playsinline to work.

I believe it's also possible to export webm directly using Adobe Media Encoder; it's also possible to use Shutter Encoder with a transparent file, set to h.265 and mp4 and choosing the GPU acceleration (which will then allow you to encode Alpha channel in the advanced options).  This should also work if you have your tags right and if the Rotato tool is no longer available.

Before I attempt to open up devices I always like to take a look at some pictures so I know what to expect; for the Empatica E4, there weren't any online anywhere.  I went ahead and took some in case anyone else wants to replace the battery without shipping it to Italy.

The mechanical design is nice, I think the castellated addition for the optics is a great idea, and they have some nice spring loaded connections to handle the geometry of their sensors.  There are two Microchip PIC24Fs as the main MCUs and it uses the silabs BLE112A for comms.  It'd be fun to spend a little more time digging into the design, but I'm strapped for time at the moment; maybe in the near future.

For me, the goal was to get my failing one back up and running after what appeared to be a simple failed lipo battery.  You can see in the pictures the battery is bulging; you can also see they use the straight up cell without the normal protection circuit that comes with many off the shelf lipos.  I ordered a replacement 300mAh battery and soldered on this JST SH 1.0 Connector and it worked no problem after a little fiddling (gotta get the fit right, the had some uniquely thin 300mAh batteries– and that lack of a protection circuit helps with the size).

Anyway, here are some pics; sorry they're not top-notch, my microscope is packed up for my upcoming move.

EasyORC

EasyOCR doesn't seem to be targeted at handwriting, so I wasn't expecting this to do particularly well.  It does target reading images of text with 80+ languages.

Link to Github Repo.

simpleHTR

Harald Scheidl's PhD work implemented as a handwriting recognition system.  I think the layout of my text might be difficult for simpleHTR to get; let's give it a shot though!  For this I downloaded the line model (which should handle multiple lines of handwritten text) that was generated May 26 2021.

Link to Github Repo.

Tesseract

Some open source code, the original version of this library was developed at HP in the eighties and nineties, and open-sourced in 2005.  Lead development was taken over by Google from then until 2018.  Seems like it could be a great contender!

Link to Github Repo.

Google API

Ship it to Google and pay $1.50/1000 instead of using something free and open source.  Of course, no github repo available.

Simple Test Results

Here's a script I wrote to compare and contrast these different systems:

from pdf2image import convert_from_path
import cv2
import numpy as np 
import easyocr
import pytesseract
from autocorrect import Speller
from google.cloud import vision

#MUST 'brew install poppler'
#MUST 'brew install tesseract'

#to test simpleHTR, I created a PNG of the text
#and ran 'python main.py --img_file ../handwritingTestImage.png'
#in its src folder after importing the line model

#for google vision API, install google CLI using
#
#"curl https://sdk.cloud.google.com | bash"
#"gcloud init"
#"gcloud projects create dramsayocrtext" #this name must be unique to your project, of all projects ever created in gcloud
#"gcloud auth login"
#"gcloud config set project dramsayocrtext"
#"gcloud auth application-default login"
#"gcloud auth application-default set-quota-project dramsayocrtext"
#
#enable API in google cloud console
#enable billing in google cloud console ($1.50/1000 images)
#
#pip3 install google-cloud-vision

SHOW_IMAGES = False
SHARPEN = False
SPELLCHECK = False
OCR_ENGINE = 'GOOGLE' # 'GOOGLE', 'EASYOCR', 'TESSERACT'

def show(img):
    cv2.imshow("img", img)
    cv2.waitKey(0)
    cv2.destroyAllWindows()



# grab handwriting pdf with convert_from_path function
images = convert_from_path('8234567890.pdf', poppler_path="/usr/local/Cellar/poppler/23.03.0/bin")
img = np.array(images[0])

# Crop to just the part with the handwriting
img = img[2*395:2*1170,0:2*827]

# Greyscale and Sharpen
if SHARPEN:
    print('using greyscale and threshold to sharpen.')
    img = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    if SHOW_IMAGES: show(img)

    sharpen_kernel = np.array([[-1,-1,-1], [-1,9,-1], [-1,-1,-1]])
    img = cv2.filter2D(img, -1, sharpen_kernel)
    img = cv2.threshold(img, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)[1]
    if SHOW_IMAGES: show(img)

# OCR
if OCR_ENGINE=='EASYOCR':
    print('using easyocr.')
    reader = easyocr.Reader(['en'],gpu = False)
    ocr_output = reader.readtext(img,paragraph=True)[0][1]

elif OCR_ENGINE=='TESSERACT':
    print('using tesseract.')
    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    ocr_output = pytesseract.image_to_string(img_rgb)

elif OCR_ENGINE=='GOOGLE':
    print('using google cloud.')
    success, img_jpg = cv2.imencode('.jpg', img)
    byte_img = img_jpg.tobytes()
    google_img = vision.Image(content=byte_img)

    client = vision.ImageAnnotatorClient()
    resp =  client.text_detection(image=google_img)
    ocr_output = resp.text_annotations[0].description.replace('\n',' ')

else:
    ocr_output = ' ERROR: no ocr tool selected. Choose "GOOGLE","EASYOCR", or "TESSERACT"'

# Spellcheck
if SPELLCHECK:
    print('using autocorrect.')
    spell = Speller(only_replacements=True)
    final_text = spell(ocr_output)

ocr_output += ' (OCRed in python; forgive typos)'

print('-'*10)
print(ocr_output)
print('-'*10)

We're going 80/20 here, and I only actually care about how well these work on my handwriting.  This is my initial test image, which I wrote on a ReMarkable tablet, filled with the kinds of phrases I might actually use:

Results

EasyOCR: "wnrivg 0 les+ Ths 1S Mq bec o Sme 6nQ . T MasSas? anj keb Iove miss Yu X , Wea} (c {C9 Crean ak US Toscnims . Sea 4PM 0t YX Hen ' _Davi&"

EasyOCR+Sharpen: "waring a Jez+ Ths 1S MQ Becl to Sme &n9 1 MSSGS anj leb Iove YbU Wiss Xu , wes F Cac iC Cream at US Toscanims Sea 4pM at Y Hlen ' ~Davia"

Tesseract: "Tw aces iS we paring a texX snipe DAS ie Ss On. - Lob 0, {ove LEPM od Cor ice Cream ok Tos canims ae . ye Hye! ai =David ©"

Tesseract+Sharpen: "Thm eae iS Wwe wary a ie cong Bee te & : weons. L Lob 0 , {ove LEPM od Gor ice Cream ok Tos canims ee i Hye! ai =David ©"

simpleHTR: "c"

simpleHTR doesn't seem to handle this multi-line image well.  Just to see what would happen if I added a simple pre-processing step to do individual lines of text, I also tried simpleHTR with this image:

simpleHTR: "This 1s e wniving Sert"

None of the local options work well enough.  Luckily, we can just use Google's actual API.

Google Vision API: "me writing a text back to someone. I let This is message love you and miss you. us weet for ice cream at 4PM at Toscaninis. See you then! -David"

It gets the words (mostly), but the line sensitivity is really high.  This happens with both text_detection and document_text_detection.    

Final Solution

We have two options: help the OCR algorithm or do the line segmentation ourselves.  Since google reports the coordinates of each word, it actually wouldn't be too hard to do the line segmentation ourselves (since we know a priori roughly how large my handwriting tends to be).  It would be nice to give the algorithm a hint about minimum line height, but that isn't currently supported.  In the name of speed, let's simply try to add lines to give the OCR algorithm a hint:

Google Vision API: "This is me writing a text message back to someone. I love you and miss Let you. us weet for ice cream at 4PM at Toscaninis. See you then! -David ☺:)"

It does seem to help; we have one out of place word (Let) and one wrong word (weet).  Passing this through the autocorrect actually made it worse ('weet' to 'went' instead of 'meet').  It also reveals how naturally slanty my writing can be without lines to write on.  For now, I'm going to simply give myself some lines in my PDF template and we'll see how well it works!

The study sparked massive outrage and articles in The Atlantic, Wired, Forbes, The NY Times, NPR, the BBC, and just about every other major news organization.  It launched an ethical sub-genre about big-tech in books and papers (1, 2)– most notably, a team of 27 bio-ethicists wrote an op-ed in Nature defending the work. It was the most shared academic research of 2014.  It's been cited almost 3000 times.

As you'll see from in my earlier essay, for a quite drastic intervention, the effect on user behavior is both incredibly small and completely unrelated to underlying affective state.  Here I will address the ethics of the study, and how it has been (and continues to be) misused by the popular press.

The Study was Ethical

Prior to the Emotion Contagion Study, the prevailing theory about Facebook was one of social reference– most psychologists would have hypothesized that the overwhelmingly positive nature of facebook posts were making people depressed and envious when considering their own lives in comparison to curated identities. Removing positive posts and negative posts were both expected to increase user well-being; it's only in retrospect, with the insights from the study, that we've come to believe that removing positive content might negatively affect users.

Given this theory, the right thing for Facebook researchers to do was to (1) check if its true, and if so, (2) change how content is curated so as not to depress everyone.  It's the right thing to do.  This research answers a fundamental, extremely important question about how we should design social media.  Sharing it with the world was a generous thing to do.

The key for this kind of study is to implement it in such a way that there isn't a real risk of causing depression or significant emotional harm to users.  Such a risk– outside of the presumed, 'common-man' risk assumed by users of the platform– requires explicit consent.  

For this study, there is no evidence that any meaningful risk was incurred.  We can see that this intervention had no practical effect on people's emotional states; once again, the leading psychologist would have predicted positive effects on user well-being if anything.  In the end, no one even noticed that the intervention was taking place– that's not an indication that something powerful, mysterious, and surreptitious; it's an indication that the changes were not a big deal.

Few people care that facebook A/B tests button color or layout– interventions with subtle psychological and behavioral implications.  Every design choice carries with it some risk; it's our job to make an a priori best guess at the possible implications, minimize uncertainty, and consent people when risks meaningfully exceed expectations.  We tacitly agree that testing UI design changes is okay, even though it might marginally affect user behavior.  We should accept continuous testing, because the company is able to improve user experience.  

This is a brand of 'rule utilitarianism'– the value is high for this kind of continuous improvement, and consenting to every small change would make the experience terrible and degrade the quality of the service.  I only should be consented when the risk to me is real and unexpected.  There are presumed, reasonable, 'common-man' risks when consuming any media.

In using Facebook, you've already willingly subjected yourself to the psychological impact of a certain kind of media.  There is no evidence that this intervention meaningfully deviated from that core experience.  Consent in this case is like consenting people for making a specific movie scene slightly more or less violent when they're already an action movie fanatic; the implicit, presumed, accepted risk subsumes the effect of the intervention.

Improper Interpretations

This study is still frequently miscited in two egregious ways– (1) it's used as an example of the callous indifference of Big Tech to user well-being, and (2) it's used as a damning example of 'the power of AI to surreptitiously and powerfully manipulate people' (see i.e. Shoshana Zuboff's famous 2019 'Surveillance Capitalism' book).  

I hope that we've adequately dismissed the first of these misconceptions above.  This was research for the common good, not something antagonistic to users.  Defining the ethical line for consent is a nuanced process, but to suggest this research was done in bad faith with nefarious intentions is disingenuous.  Facebook had no incentive to publish this result publicly if they had truly poor intentions, and it's obvious that the researchers didn't see their work as unethical.  No one would've willing subjected themselves to the mudslinging, PR nightmare that ensued from this publication.

The second conception of this study– that this is evidence of Big Tech's ability to powerfully and subliminally manipulate users– is also clearly wrong.  It follows from misconstruing 'a statistically significant effect' (which there is) with a 'powerful and important effect' (which there is clearly not), and making an invalid leap from a behavioral measurement to an underlying emotional state.  It's pushed along by a widely-held, blatantly wrong view that subtle design choices exert a powerful influence on human behavior– a view with roots in discredited and inaccurate social priming research.

To reiterate, this incredibly invasive intervention on emotional facebook content has nearly negligible effects on user behavior, and no known effect on user well-being or affect.

This paper is not evidence of either a big-tech conspiracy or a new breed of sophisticated coercion.  Its proper interpretation makes the opposite point.  With this research, Facebook took a step to understand, contextualize, and share the emotional impact they have on their users.  They demonstrated a very tiny behavioral effect with a dramatic intervention.  

It seems that if Facebook were to delete most of the positive posts on your newsfeed, you probably wouldn't notice, and you probably wouldn't care.

Pop-psychology needs to be approached with a high degree of skepticism. Poor statistical techniques, biased framing, and hyperbolic misinterpretation are endemic to psychology's popular science press.  In this post, I've collected a few other famous examples of popular science gone wrong.

Why We Sleep

One of my MIT mentors suggested I read Dr. Matthew Walker's 'Why We Sleep?' as part of my research.  It's a New York Times Bestseller; Bill Gates had this to say:

Why We Sleep is an important and fascinating book…Walker taught me a lot about this basic activity that every person on Earth needs. I suspect his book will do the same for you.

With this book, Matthew Walker launched himself into the limelight; he's appeared on 60 Minutes, Nova, BBC, NPR, and has glowing reviews across all the major news outlets.  He is single-handedly shaping the discourse on sleep, and shaping the behavior of thousands of readers as well.

Why We Sleep was then picked apart very thoroughly by Alexey Guzey.  His post focuses on just fact-checking the first chapter, which he calls 'riddled with scientific and factual errors.'  The review is thorough, and I highly recommend reading it (Andrew Gelman recommends it too).  He points to outright academic misconduct in the way data is presented which UC Berkeley has ignored.

While Walker was forced to issue some corrections, this book is still out there.  Moreover, a Google search of 'Why We Sleep' doesn't include any criticism on the first page of results; only testimonials to the power of this work.

Thinking Fast and Slow

Another book– which I actually loved– is Daniel Kahneman's Thinking Fast and Slow.  Daniel Kahneman has done a lot of great scholarship in my opinion; unfortunately, he had to retract the entire fourth chapter of his book, on social priming, after publishing an open letter in Nature warning of a looming 'train-wreck' for the field when some of the core findings failed to replicate.

This was largely in response to an analysis done by Ulrich Schimmack, who runs one of the best blogs on the replication crisis.  Just last year he published a further critique of Thinking Fast and Slow (2020), in which he analyzed each chapter with his 'R-Index' (a score which assesses the likelihood of replication based on the power of each cited study, though this is highly variable when used to analyze just a small numbers of studies).  The results are pretty bad.  Out of the 13 chapters analyzed, the majority (seven chapters) fall below a 50% likelihood of replication (on average for the studies in that chapter); the other six vary widely, mostly hovering in the fifties and sixties.  Those odds are not great.  Schimmack summarizes:

[Kahneman's] thoughts are based on a scientific literature with shaky foundations. Like everybody else in 2011, Kahneman trusted individual studies to be robust and replicable because they presented a statistically significant result. In hindsight it is clear that this is not the case. Narrative literature reviews of individual studies reflect scientists’ intuitions (Fast Thinking, System 1) as much or more than empirical findings. Readers of “Thinking: Fast and Slow” should read the book as a subjective account by an eminent psychologists, rather than an objective summary of scientific evidence. Moreover, ten years have passed and if Kahneman wrote a second edition, it would be very different from the first one. Chapters 3 and 4 would probably just be scrubbed from the book.

It is worth reading Kahneman's direct response and acceptance of Ulrich's reporting in his 2017 post 'Reconstruction of a Train Wreck: How Priming Research Went off the Rails.'  This is, of course, slightly ironic, as Kahneman calls out underpowered research specifically in his book as part of a discussion on 'the law of small numbers'; Kahneman acted admirably, though, in accepting and supporting the critique.

Before You Know It

'Before You Know It: The Unconscious Reasons We Do What We Do' is written by John Bargh, the father of the notion of 'social priming', which has failed to replicate.  (Two of his most famous studies – that warm beverages make you act with warmth, and that read words associated with aging make you walk slower–  are now debunked.)  This book has also been covered by Ulrich Schimmack in an excruciating detailed, wonderful post.  He estimates the replicability of the cited studies from each chapter based on their power:

The more important question is how many studies would produce a statistically significant result again if all 400 studies were replicated exactly.  The estimated success rate in Figure 1 is less than half (41%). Although there is some uncertainty around this estimate, the 95% confidence interval just reaches 50%, suggesting that the true value is below 50%.  There is no clear criterion for inadequate replicability, but Tversky and Kahneman (1971) suggested a minimum of 50%.  Professors are also used to give students who scored below 50% on a test an F.  So, I decided to use the grading scheme at my university as a grading scheme for replicability scores.  So, the overall score for the replicability of studies cited by Bargh to support the ideas in his book is F.

The best performing chapters are chapter 10, where 62% of the studies should replicate if done exactly, and chapter 6, where this is true of 57% of the studies.  All other chapters have estimated replicability of <50% (a low of 13% appears in Chapter 3).

Keep in mind this is just based on the statistical power of the study– we're estimating if the same study was repeated exactly, how likely it would retain a 'significant' result.  This is different than whether an effect is real and meaningful or not.  Other studies can be done with much larger sample sizes (what we typically mean by replication in social science), and many of the concepts may well be disproven already as a result.  Marginal, meaningless effects can replicate 'significantly' if the study had a large enough sample size to capture them.  Schimmick's critique is really about methodology– the trust we can put in these specific set of papers agnostic of other information.

Glow Kids

I've written a more extensive essay on this particular book; Kardaras mistakenly cites some purely fabricated research within it (the study's author is the subject of a criminal complaint for fraud). It's unfortunate that this 'research' was featured in Glow Kids– a book whose premise I really appreciate.

Behave

Sapolsky was prominently featured on a Radiolab episode questioning free will; in it, he cited a famously incorrect study on judges.  This study also features prominently in his book, Behave.  The study suggests that hunger drives favorable parole verdicts down from 65% after a break to 0% just before one.  Sapolsky interprets:

What's interesting about that? Number one, the biology makes perfect sense. What are you doing there when you are a judge trying to judge somebody from a completely different world from you to reach a point of deciding. There's mitigating fact. You're trying to take their perspective. You're trying to think about the indirect ways that let -- you're using your frontal cortex. And when you're hungry and your frontal cortex isn't working as well, it's easier to make a snap emotional judgment: this person's rotten. The second amazing thing which exactly addresses this issue is, you get that judge two seconds after they made that decision, you sit him down at that point and say "Hey, so why did you make that decision?" And they're gonna quote, I don't know, Immanuel Kant or Alan Dershowitz at you. They're going to post-hoc come up with an explanation that has all the pseudo-trappings of free will and volition, and in reality it's just rationalization. It's totally biological.

Of course, it turns out the cases were actually ordered by severity of offense and this idea that hunger drives a judge's decision has no basis in reality.  Daniel Lakins points out the absurdity of this finding– "if hunger had an effect on our mental resources of this magnitude," he writes, "our society would fall into minor chaos every day at 11:45".

Positivity

Positivity is famous as the book in the positive psychology movement, written by Barbara Erickson.  She has faced significant criticism for her views on positivity– her famous suggestion that a golden 2.9013 to 1 ratio of positive to negative emotions separates those that flourish from those that languish was publicly debunked, and forced a retraction of a chapter of this book; despite that, Fredrickson continues to defend the premise that there is a tipping-point ratio of positive to negative emotions that tips people between the two outcomes (and continues to be criticized for it).

Humanistic psychologists have been skeptical of the oversimplifications of positive psychology, and Fredrickson's conception of fulfillment is one major example.  More positive feelings don't seem to directly lead to fulfillment.  Many deep thinkers would actually suggest that voluntary, efficacious self-sacrifice is quite important instead.  

It is quite unlikely that all humans across all stage in life and all contexts will obey a rule.  It also directly contradicts pretty well-established notions of hedonic adaptation– that we don't spiral when confronted with a temporary state of bad or good emotions. People are actually quite robustly adaptive.

These kind of simplifications– without empirical data to support them– push positive psychology further from its intended purpose, and do more harm than good for people that are in search of meaning in their lives.  

Stumbling on Happiness

I really enjoyed Dan Gilbert's Stumbling on Happiness; Gilbert is a talented and well-read author, and I think his work stands out as an interesting synthesis of many ideas.  Unfortunately, Gilbert falls into many of the same traps as the others; his reporting of underlying research seems fraught with mistakes and difficult to trust.  Gilbert incorrectly cites the debunked social priming research, and particularly mischaracterizes research on agency and alexithymia in ways that are pretty detrimental to his argumentation.  I've written more extensively about the issues I have with some of his characterizations of the underlying research here if you're interested to learn more.  

Counterclockwise

Harvard's Ellen Langer features in Dan Gilbert's work as proof that agency matters for longevity, though her research doesn't seem to offer empirical support for that conclusion (as discussed in my post on Stumbling on Happiness).  Some of Langer's work has been called out in quite a bit of detail by James Coyne and Andrew Gelman.  Langer's book also suffers from several small references to debunked social priming research.

Instead of rehashing the mistakes shared with other examples, we'll take a look at the thrust of the book, which focuses on its namesake– the Counterclockwise Study.

In 1979 Harvard's Ellen Langer took sixteen men in their 70s and 80s, and had them go on a retreat where the environment and media were designed to exactly replicate life 20 years earlier. Half of the men were told to live as if it was the current day– they discussed events from two decades prior as if they were unfolding and could not reference anything in their lives after the events.  The other half were told to reminisce with each other about the earlier era they were re-experiencing.  

She reports that both groups had hearing, memory, height, weight, gait, posture, and grip strength improvements; they both also 'looked younger' as judged by blinded raters.  The experimental group "showed greater improvement on joint flexibility, finger length (their arthritis diminished and they were able to straighten their fingers more), and manual dexterity. On intelligence tests, 63 percent of the experimental group improved their scores, compared to only 44 percent of the control group."  This study led to a four hour BBC mini-series in 2010 called The Young Ones, where they repeated the same experiment with six older celebrities.

Unfortunately, it's hard to trust these results outside of what intuition confirms.  The testing suite appears extensive, the sample size is terribly small, and the participants are certainly aware of the desired results (and appreciative of the researchers for their experience).  Given the number of tests, the high variability of small samples, and the demand characteristics, it seems very likely at least a handful of results would come back 'significant' regardless of real underlying causality.

Despite that, the only quantitative difference– 63% vs 44% of participants improving in intelligence– merely sounds impressive.  This is a manipulative framing of the underlying data; it's better described as 5 of 8 in one group vs. 4 of 9 in the other. (I assume; earlier Langer states 8 people are in the both groups, but 44% of 8 gives 3.5 people.  One of the numbers must be incorrect– another red flag.)   A difference in one person for groups of this size is not meaningful.  Over the course of the (at least) twelve different tests administered, several will have this difference.

There are no peer reviewed publications associated with this study, either; for all the effort, it is described only briefly in her book, bracketed with very few interpretive statements.  It seems like a cautious resignation to the minimal empirical value of the study's quantitative data.  However, on page 167, she makes one overstatement:

The most dramatic example of language acting as placebo can be found in the counterclockwise study. The study used language to prime the participants, asking the elderly men at the retreat to speak about the past in the present tense. With language placing the experimental groups’ minds in a healthier place, their bodies followed suit.

To be clear, that isn't to say that a meaningful difference between groups doesn't exist, only that the statistics and anecdotes derived from such a severely underpowered study couldn't possibly have captured it.

The question remains– does acting like your younger self make a difference compared to reminiscing?  Luckily, we can expect some rigor to end this story.  Langer pre-registered a large scale replication to be carried out in 2020 in collaboration with an Italian team.  Unfortunately, 'gathering a hundred 80 year olds in Italy' is the fastest way to get your research shut down during a pandemic– hopefully we'll see some results once things return to normal.

Perhaps the biggest questions are the ones left unasked.  It seems quite obvious that bringing a group of dependent, isolated 70-80 year olds together on a week long nostalgia trip will revitalize them.  Even with a small sample we can make that inference. The New York Times described the BBC participants as "apparently rejuvenated... [they] walked taller and indeed seemed to look younger. They had been pulled out of mothballs and made to feel important again."

How much of that is because they are have structured social time with peers?  How much because they are breaking their routine and experiencing something novel together?  How much because the environment and media are all visceral, nostalgic primes that reawaken latent, more vital and youthful self-concepts?  How much because they are the subject of an important and meaningful scientific study?  How much did it matter at all?

Aging is both a psychological and biological shift.  It's certainly true that the psychological component is powerful, but it seems unlikely that the benefits here come from a re-conception of oneself as explicitly younger or a change of verbiage from past to present tense.  In reality, most of the benefit will come from a renewed, socially-reinforced sense of feeling of purpose, agency, and novelty.

Pre-suasion

I've discussed some of Cialdini's misinterpretations before, and have a detailed description of some of the mistakes in this particular book here.  Conceptually, Cialdini in this text broadly argues that very subtle (sometimes subconscious) interventions have a large effect on our decision making.  This idea sits at the core of the replication crisis in social psychology.  While there are some good insights in the book, they stand alongside several examples of weak empirical data.

Misbehaving

One of the most popular examples of the 'power of defaults' in behavioral economics comes from Johnson and Goldstein's 2003 Science paper 'Do Defaults Save Lives?', which is frequently used in a misleading way to suggest that for complex decisions, we get overwhelmed and will simply choose the default.  This is a misinterpretation of the data– it turns out that many places have presumed consent, or don't take the consent seriously.  Meta-analyses have not show the large effects typically attributed to the phenomena.

Thaler gives a full and reasonable treatment to the topic of opt-in and opt-out in his book, clearly aware of the problems I listed above.  He settles on a policy suggestion of 'mandated choice' for organ donation, not at all relying on a 'default effect'.  

Despite the careful thinking, he states that "[t]he findings of Johnson and Goldstein’s paper showed how powerful default options can be”, suggesting that these misleading results prove that the default choice effect is still powerful and important, just not binding for this specific case.

While this is a relatively minor problem, it's a misattribution worthy of note.  It perpetuates a conception of human decision making that I believe is flawed– that very subtle changes drive important and complex decisions.  The default effect may be real, but not when meaningful outcomes are on the line.  This concept applies only when a decision is low-stakes and preferences are weak.

Generalizing the Evidence

These are some of the most famous examples of popular science books, written by very reputable and trustworthy academics (two of whom have Nobel Prizes and whom I admire greatly).  In general, their mistakes are evidence of a lack of rigor in analyzing their sources.  (To be fair, sources are hard to trust given the state of the replication crisis in the academic literature.)  Mistakes range from relatively minor and sporadic (for Thaler) to quite major (entire books for Kahneman and Walker).  

Unfortunately, any error– whether sporadic or frequent– undermines a text's trustworthiness.  We're forced to fact check works of popular science instead of taking them at face value.  

It seems the available evidence points heavily towards a presumption of guilt in popular science accounting, at least as far as social psychology is concerned.  Until you've vetted an author, these books are better conceptualized as pointers to a collection of potentially interesting primary sources.  Pulling signal from the noise requires statistical fluency, patience, and rigor.

Glow Kids and Screens Themselves

I think about quite a bit is the separation of hardware and software. Most research really focuses on the software level– app design and content.  It's definitely true that dark patterns and design hacks are making the software landscape an addictive, cognitive landmine for all of us.

However, from the pioneering work of Michael Posner (the world's leading authority on human attention), we know that changes in motion and luminance drive the reorientation of our attention at a neurological level.  Screens are an interface that embodies these two principles; by nature, they reorient and distract us from anything else that we might be focusing on.  There are real problems with the screen itself, and I was excited to read a book that seemingly focused on this issue.

The book doesn't really focus on screens in themselves, but rather 'screen culture'.  Within it, Dr. Kardaras includes interesting points that are worthy of further exploration.  He makes a compelling case that the committing realistic, simulated violent acts might have negative repercussions (suggesting that Dr. Chris Ferguson, the main proponent that video games don't influence violence, fails to account for mediating variables in his epidemiological research).  He dovetails this point nicely with his description of his video game addiction counselling work.  The stories of dissociation and anger that accompany severe video game addiction are quite sobering.  

He also weaves a compelling story about the infiltration of screens into the classroom despite all available evidence pointing to the fact that it is detrimental for student outcomes.

Slightly Questionable Reporting

Unfortunately it's hard to take the book completely at face value.  He treats the possible health effects of electromagnetic radiation (EMF) with a dramatic flair than I believe is unwarranted.  We don't have much strong data on this subject since ubiquitous EMF is so recent, and Dr. Kardaras is correct that we know that cell phones warm the tissue in the brain and that some evidence shows they increase the risk of brain glioma.  This finding is controversial though; while there is some epidemiological support for it, there have been large studies that show no effects, and the jury is still very much out.  

As Kardaras reports, a team of scientists working on behalf of the WHO did label EMF a Group 2B 'possible carcinogen' in 2011.  But this label is best understood as 'can't be definitively ruled out for causing cancer'.  For a long time, coffee also had the 2B designation (it was recently downgraded to Group 3); pickles and aloe vera still reside there.  Red meat has a worse designation– 2A; processed meat falls in category 1.  We don't have clear data either way, but that ambiguity means that even if a cancer risk is real, we can be confident it will be small.  As far as we know, EMF is as dangerous as pickles.

Kardaras also correctly mentions that there are researchers associated with Harvard MGH investigating the link between EMF and autism.  The primary author, Dr. Martha Herbert, is a neurologist and an assistant professor at Harvard Medical School; it seems fair to call her 'controversial', in that her views on causal forces driving Autism are not mainstream.  She has a very holistic interpretation of the environmental drivers of autism; while she's not an anti-vaxxer, she does leave the door open for a causal pathway from vaccine to autism expression in her PBS NewsHour interview.  Even with these things in mind, she herself would not lay autism at the feet of EMF.

I don't think these opinions are fairly contextualized or nuanced in 'Glow Kids', which is a shame.  I expect it will stir an urgent sense of fear in its audience over a risk that is very, very mild.  

A Bad Citation

The most interesting study that Dr. Kardaras cites in his book implies that our perceptual acuity has been measurably decreasing over decades— we can distinguish fewer shades of color, fewer sounds, etc– due to screen culture.  He writes:

According to longitudinal research conducted by the German Psychological Association (GPA) in association with the University of Tubingen over a 20-year period, we are shockingly losing sensory awareness at a rate of 1 percent a year.

This research began in the 1960s after teachers working at the university noticed that, after the proliferation of television viewing in the 1950s, students seemed to suffer from a severe reduction in their sensory awareness; they appeared less alert than previous generations to information from their surrounding environment, which, in turn, was adversely affecting their ability to learn. The university then partnered with the GPA in order to quantify this phenomenon.

The researchers conducted sensory tests on 400 undergraduates per year over that 20-year period—a total of 8,000 subjects. The results shocked even the researchers; each successive cohort was slightly less sensitized than the prior cohort: “Our sensitivity to stimuli is decreasing at a rate of about one percent a year,” their report stated.

According to pioneering, visionary educator Joseph Chilton Pearce, author of Magical Child (1992), who wrote extensively about the study in his 2002 book, The Biology of the Transcendence: “Fifteen years ago people could distinguish 300,000 sounds; today many children can’t go beyond 100,000 . . . Twenty years ago the average subject could detect 350 different shades of a particular color. Today the number is 130.”

This section goes on for a while longer.  It's an incredible claim, and the most exciting one in his book.  The citation comes from this article by Michael Kneissle of the Waldorf Research Institute.  

The linked paper quotes the study behind these numbers– a study conducted by psychologist Henner Ertel.  I searched for any other research that would back up this claim and came up empty-handed; all roads lead back to this one article featuring Henner Ertel.

Unfortunately, there is no trace of Ertel in the peer-reviewed literature.  His name does appear in two other places, though. It first appears in an article called ‘Sold for Stupid’, an article about Ertel's GRP– a fake, pseudoscientific research institute with two employees, known for mass producing fraudulent, sensational headlines on a wide range of research topics.  The other result is Ertel's entry on a pseudoscience watchdog page.

Ertel has been the subject of a criminal complaint for his academic fraud.  It further appears this sham psychologist threatened ‘Zeit Online’ with a defamation suit, and has a history of threatening scientists that question his validity with lawsuits of their own.  

Ertel's fake organization is called the Rational Psychology Association (Gesellschaft für Rationelle, Psychologie, GRP). His 'relationship' with the University of Tuebingen comes from a direct quote by Ertel himself in the linked article above. As for the other author Dr. Kardaras cites directly– Joseph Pearce– his book contains the same paragraph almost verbatim, but with no citations.

Zeit Online reports that the main target for Ertel's fraud has been Men's Health magazine.  It seems Ertel managed to fool the Waldorf Institute, Joseph Chilton Pearce, and Dr. Kardaras as well.  

Fin

This citation is pretty unfortunate– when I clicked on the link for the article I was immediately suspicious.  Dr. Kardaras fell prey to motivated research.  It's too bad, because I agree with much of the thrust of the book, and Dr. Kardaras could have preserved most of his points without these bad citations.  Instead, his readers are forced to check the sources and approach the text with a healthy dose of skepticism.

The Basics

When we evaluate a causal claim, we split our data into a control group and an intervention group– let's test whether aspirin prevents heart attacks (p<0.0001).  Our control group doesn't take aspirin, and our intervention group takes it daily; now we look at each individual's rate of cardiovascular events per year, by group (around 0.5% for both).  We assume both the intervention and control data are normally distributed, and we looking to see if data from the intervention group has a different mean than the control.  

Assuming we have two groups as Gaussians we are sampling from, we can then try to answer some common sense questions.  Given the data in the control group, we can estimate a mean and variance– how likely are we to draw the data we see in the intervention group from the control group distribution?  How confident can we be in our estimates of means and variances given a certain number of observations?

P-values quantify the likelihood that some observed intervention data is simply the result of randomness in sampling from the control distribution.  A statistically significant effect is a categorical distinction on top of that p-value– i.e. we call an effect 'statistically significant' when it would be unusual to observe the intervention data simply by drawing randomly from the control distribution, where 'unusual' is an arbitrary standard.

The term 'statistically significant' leads people to conflate measurable effects with significant effects.  'Statistical significance' is meant to convey that the data is suggestive of a true underlying relationship, not that it's a large enough effect to matter practically.  'Statistically significant' relationships are not necessarily important ones.

But the issues with the 'statistically significant' don't just end with its semantics.  Even as a way to understand whether data is giving insight into a real underlying relationship, the concept fails without proper context and understanding. Categorical distinctions like this are not useful in the literature and harmful to scientific progress.  The term is confusing and we should stop using it– and I'm not the only one that thinks so.

What People Are Saying

Andrew Gelman– one of the best living statisticians– famously published a 2006 paper entitled "The Difference Between “Significant” and “Not Significant” is not Itself Statistically Significant" which showed "that even large changes in significance levels can correspond to small, nonsignificant changes in the underlying quantities."  In 'Using Effect Size– or Why the P Value is Not Enough', authors Sullivan and Feinn start their piece by quoting two of the most influential statisticians of the modern era:

Statistical significance is the least interesting thing about the results. You should describe the results in terms of measures of magnitude –not just, does a treatment affect people, but how much does it affect them.

-Gene V. Glass

The primary product of a research inquiry is one or more measures of effect size, not P values.

-Jacob Cohen

The above statisticians are not alone; in 2016, the American Statistical Association officially published a public statement urging caution around the use of p-values.  Among many points about the lack of usefulness of p-values, one important point that a "p-value, or statistical significance, does not measure the size of an effect or the importance of a result."  They followed it with a 2019 special issue entitled "Statistical Inference in the 21st century: A World Beyond p<0.05". The headline article has a section labeled "Don't Say Statistically Significant":

The ASA Statement on P-Values and Statistical Significance stopped just short of recommending that declarations of “statistical significance” be abandoned. We take that step here. We conclude, based on our review of the articles in this special issue and the broader literature, that it is time to stop using the term “statistically significant” entirely. Nor should variants such as “significantly different,” “p < 0.05,” and “nonsignificant” survive, whether expressed in words, by asterisks in a table, or in some other way.

A 2019 editorial in Nature followed this issue, summarizing the movement against 'statistical significance' in plain language.  With more than 800 signatories in the field, they "call for the entire concept of statistical significance to be abandoned."

When evaluating papers, it's much more important to understand the effect size and power, and put that effect in context of what it means with respect to a broader understanding of the subject.  Making sense of the literature in a world that statisticians have admitted is fundamentally flawed is a non-trivial exercise for the those of us without a stats degree.

What Statistical Significance Really Means

'Statistically significant' is based on some arbitrary, probabilistic standard– i.e. the data suggests a measurement is unlikely to be the result of random chance.  Frequently we set this arbitrary point at 0.05– so if the p-value is  less than 0.05, we label a result as 'statistically significant'.  That means, if there is no real effect– if we assume our data was the result of random sampling– the odds of seeing this outcome is <5%.  Every 20 times we run a test with the criteria p<0.05, if there is no underlying relationship, we'd expect to hit this threshold once.  

Of course, this kind of thinking doesn't scale very well across many studies and many researchers.  If this was our only standard, we'd expect that for every 20 times someone tests a bogus theory, one result will 'confirm' (p<0.05) a real effect when there isn't one.  If every scientist is focusing their effort on implausible theories, the literature will be dominated by false positives–  we'd especially expect popular misconceptions to have statistically significant results.  

We need data from all of our attempts to study a hypothesis, or else we can't contextualize any single attempt.  Since authors tend to publish their positive results and not their negative results (the so-called file-drawer effect), and publications reinforce this bias in the review process (publication bias), we're left with overwhelmingly spurious results in the literature using this simple pass/fail technique on an arbitrary p-value threshold.  

It's also very easy to inadvertently p-hack– if we test 20 theories on one set of data, we'd expect 1 to be 'statistically significant' with p<=0.05 even if no true relationships exists.  This kind of poor methodology was common in the social sciences for a long time (i.e. test 20 theories on the data you collect, but only publish the one that 'hits' with p<=0.05).  It's very natural, when an initial hypothesis fails, to consider other explanations that the data could reveal.  Fighting this urge, and rigorously testing only your a priori hypotheses, can be very unintuitive to people with poor statistical literacy.  In my opinion, we still do not train people against this rigorously enough.  Selectively publishing the details of this kind of approach has dire consequences for the overall trustworthiness of scientific literature.  

Beyond the pitfalls of publishing fair and accurate p-values, it's still common to misunderstand them conceptually.  It's a subtle but very important distinction to conclude 'repeating this experiment, you'd expect this or larger divergences 5% of the time simply due to randomness' (the correct interpretation) as opposed to 'the odds that my hypothesis is wrong is 5%' (terrible).  The American Statistical Association reiterates: 'By itself, a p-value does not provide a good measure of evidence regarding a model or hypothesis.'  They are very clear that the existence of an effect or association should never be assessed on p-values alone.  If that seems unintuitive to you, don't worry, 86% percent of statistics teachers also get this wrong.  (The linked paper, 'Mindless Statistics' by Gerd Gigerenzer, is an excellent and sobering indictment of the modern practice of statistical techniques.)  Gigerenzer has also experimentally shown that 40% of psychology professors gravely misunderstand what statistical significance means.

In a vacuum, moving from a p-value to an estimate in the odds of a hypothesis being 'correct' will depend on the effect size and your prior (how likely we believe the hypothesis is of being true).  In the broader scientific context, this kind of result would suggest further exploration– the odds of a correct hypothesis would then be revised by considering several studies, each with a different p-value that captures some underlying notion of uncertainty.

If we wanted to comment on the odds that a hypothesis is wrong given a p-value, we need to calculate the positive predictive value (PPV) as explained (excellently) here by Felix Schonbrodt.  Based on meta-analysis of these disciplines, we know roughly the likelihood that a study is true given a 'significant' result (26-39% for social science, based on statistical analysis and further corroborated by replication studies).  Incorporating this kind of information allows us to guess the likelihood of truth conditional on the information we have available in a Bayesian way.

All of this makes the p-value a remarkably difficult thing to interpret.  How can we tell whether a p-value is meaningful when there are is so much bad practice centered around them?

The Heroes we Need

Fortunately, there are ways to understand whether p-values actually mean something.  Whenever I have a statistical question, I turn to my favorite sources on the subject– Professor Andrew Gelman's Blog and Professor Ulrich Schimmack's Blog.  

As we saw above, it's possible to incorporate some knowledge of the meta-statistics of a discipline to make a quick assessment of the predictive value of a given p-value without further information.  But there is a lot more to consider– the same p-value across different contexts can have very different meanings.

Professor Ulrich Schimmack is the best person to look towards for detailed advice on this subject.  In his excellent blog post "Men Are Created Equal, P-Values Are Not", he discusses how you can analyze a researcher's p-value distribution and estimate their 'file-drawer rate', the probability of p-hacking, and the likelihood of replication.  These kind of analyses take into account the power of a researcher's studies (which we'll talk about in a moment).  It's also possible to look at meta-studies and p-score distributions within publications to assess publication bias.  

Professor Schimmack takes it one step further with his "Personalized P-Value" post.  Beyond bad statistical practices (like file-drawer/p-hacking), different researchers can also have different practices– i.e., they can analyze and prove obviously correct hypotheses with a high hit rate, or they can look for relatively obscure and surprising insights with a low hit rate.  

Imagine two researchers– one that investigates the size of obvious effects, and one that's looking for counterintuitive insights.  They both perform 20 experiments; the first researcher finds 19 'statistically significant' results with p<0.05, while the second finds only one. If we look at any one of the 'statistically significant' results, can we make a guess about whether one is more likely to be true based on the researcher?

While both approaches are valid and valuable, the same p-value conveys a very different 'likelihood of revealing a real underlying effect'.  Luckily, both of these research strategies show up in their p-value distributions.

How to Read (Social Science) Papers

What does this mean for how we read a paper?  I'm going to focus on social science (my area of interest), but the same applies for other fields that struggle epistemologically (medicine, neuroscience, and machine learning all come to mind– take at look at the very enlightening 'Are All GANs Created Equal?' from some insight on how this applies to machine learning research).  

Sadly, when it comes to making claims about social psychology, at the moment you're better off guessing (or asking your friends) than trusting the literature.  Prediction markets do a great job predicting replication; check out this sobering chart from Nature Human Behavior on social science articles published in the top impact journals:

If you can find a scientific prediction market, that's actually a great place to check your instinct about a paper.  DARPA is actually funding such a project.

It turns out we all spend quite a bit of our time observing human behavior.  You should have strong priors in social science, and in the absence of a consensus mechanism, you should trust your intuition.  Moreover, we established earlier that less than 40% of 'significant' studies replicate, regardless of journal (and that number is closer to 26% for social psychology)– so your prior for the truth of a paper should be quite low (a 'significant' result in a paper should bias you towards believing it's more likely false than if you hadn't encountered it in the literature).  This trend applies regardless of the year (but hopefully that will change!) *

Furthermore, inaccurate studies are cited significantly more on average, and retractions don't seem to change citation behavior.  Meta-analyses suffer from similar problems.  Science journalism is very biased and misleading in what they report.  As anti-scientific (and horribly depressing) as it is, our simplest and best first-order heuristic is our gut.  

But all is not lost.  There is real and useful information in the literature if we work hard at extract it.  To do so requires a search for replication attempts and meta-analyses (1, 2, 3) supplemented with general background research.  Many big ideas have been scrutinized, and there are great blogs and journals that focus on this topic– I highly recommend checking Andrew Gelman's blog, Ulrich Schimmack's blog, Nick Brown's blog, Retraction Watch, Data Colada, Initiative for Transparency in the Social Sciences, Brian Nosek's Center for Open Science (OSF) and their Reproducibility Project, and the Replication Network.  You might also skim the writings of Daniel Lakens, Jesse Singal, Gavin Leech, Alvaro de Menard, or Felix Schönbrodt.

There are also several specific concepts that have been discredited.  Simple background searches are imperative.  It's important to check the Retraction Database to see any notes; if a paper is modern and you can't find any red flags, statisticians like Andrew Gelman recommend scaling all effect sizes down by an 'Edlin factor'–  between 1/2 and 1/100 of what is reported– conditional on the methodology.

For a more in-depth analysis of an individual paper, we can also check Shimmack's rankings of the 400 most prominent social scientists and rankings of the top 120 social science journals to see how trustworthy an author/journal combination truly is.  His blog is also a gold mine of useful context.

If you really believe a topic is important and no one has done any fact-checking, you can also do it yourself.  Nick Brown offers a simple forensic tool for statistics called SPRITE that attempts to back out underlying distributions from summary statistics.  Don't be afraid to reverse engineer the analysis.

Taking into account all of this secondary information, it's possible to critically examine the literature with a well informed prior, and to fairly contextualize the power and effect size of a given study.  Most of our work for reading a paper in social science must be done at the level above an individual paper.  

Useful information is there for us with proper skepticism and scrutiny.  Great claims require great evidence.

What does this Mean for Our Research?

So by now we've done our best to destroy the concept of the 'statistical significance' and to rethink our analysis of the existing literature; now how do we apply this to our research?  Below are a few best practices to apply to our work.

Report Several Measures (Correctly)

In terms of reporting results, we should report an effect size that has been normalized by the standard deviation (Cohen's D or Odds Ratio), a p-value (without any additional commentary), and a confidence interval (which takes into account the variance normalized by the sample size to give us an estimate of standard deviation over distributions).  We should be careful and thorough in interpreting our results– keep the PPV in mind, and do not make the mistake of equivocating a p-value of 0.05 with a 95% chance that your hypothesis is correct as more than half of studies do.  

Create an Explicit A Priori Hypothesis and Pre-Register

Most importantly, we should be very explicit about exactly what hypothesis we will be testing before we start our study design and only test that hypothesis; and to make sure we're not wasting time with an underpowered study, we need to set out with an appropriate sample size.  You should then pre-register your study publicly, at a place like Wharton's Credibility Lab or The Center for Open Science.

Conduct an A Priori Power Analysis to Choose Your N

If we make a mistake, it will be because we either find an effect that isn't real (type 1 error) or fail to capture an effect that is real (type 2 error).  Type 1 errors are clearly more catastrophic, but type II errors are also common in fields where effects are small and noisy, and recruiting large groups of participants is difficult.  When we do a power analysis, we can set a threshold for our probability of making a type 1 error (alpha) as well as a type 2 error (beta).  A study's power is the inverse of beta (1-beta)– i.e. the likelihood that you measured an effect if one does exists.

We should use a power calculator online (or a tool like UCLA's G*Power) before we do a study to calculate N. We need to know the type of statistical test we're using, the alpha (usually 0.01 or 0.05), the expected effect size, and the power we want to achieve (usually 0.8-0.9).  With that information, we can calculate the sample size we'll need to measure an effect if one exists 80-90% percent of the time with a p-value of 1-5%.

Broaden your Toolset

Fisher– the 'inventor' of p-values and the father of modern statistics– was deeply flawed in his thoughts about our ability to reason causally.  The tide of Bayesian logic is swiftly overtaking the bad practices he instilled years ago.  Even he believed that this kind of analysis was basic and should only be applied where little contextual knowledge was available, and never with a specific p-value threshold.  Many of the defining statisticians that followed were very critical of the concept.

There are many other statistical tools available– Gigerenzer points to "descriptive statistics, Tukey’s exploratory methods, Bayesian statistics, Neyman–Pearson decision theory and Wald’s sequential analysis" in his 'Mindless Statistics' review.  It's our job to get to know these tools, to spend time understanding the statistics, and to never take a result at face value without understanding the math behind it.  Science is contingent on putting in the hard statistical work.

And of course, don't forget the most important bit of advice:

Never Say 'Statistically Significant' Again

* The idea of replication itself is, in many ways, based upon this categorical definition of 'statistically significant'.  We can assess 'replication' by looking at a 'statistically significant' result and then forming a wholistic picture to see if that result is accurate-- in this way, there is a very real replication crisis.  It's almost impossible to know whether a given paper is accurate at face value and many results that are taken as 'true' are simply not.  

It's worth noting, though, that a 'significantly significant' study that then comes up in another, higher powered study as *not* 'statistically significant', doesn't mean the two studies are contradictory, and doesn't necessarily mean that someone utilized poor research methodology.  These two datasets can be analyzed and reconciled as a whole, more accurately sculpting an underlying stochastic model of the world.  We have to be careful when we talk about the 'replication crisis' as much as any other statistical concept.  

Rationality in Economics

In economics, the word 'rational' is used to describe self-consistency– i.e. if you prefer A over B over C, you prefer A over C.  You have a consistent utility function and full knowledge.  Homo economicus is rational and self-interested.

This of course has evolved into 'bounded rationality' in decisions that take into account cognitive limits, costs, and biases.  This concept was coin by Nobel-prize winning economist Herbert Simon, and updated by Gerd Gigerenzer– much of the conversation describes heuristics for decision-making that might be more optimal when accounting for decision costs; the debate rages on whether these concepts are 'biases' and flaws in cognition that we need to correct for, or adaptive and optimal.  (For instance, the cognitive flaw described as the 'mere exposure effect' to prefer and select things that we recognize has been recast by Gigerenzer as the 'recognition heuristic', in which ignorant tennis fans select winners based off recognition better than those that follow the sport).

An ethical corollary to bounded rationality is rule utilitarianism– we should act in ways that conform to principles of behavior.  Even when a local decision is sub-optimal, reinforcing the moral principle is important for both building robust habits in the face of ethical quandaries and minimizing the decision costs.  A common example of this is stopping at red lights– if at every intersection we all got out and presented an argument about who has a greater ethical case for going first, the decision cost outweighs the ethical cost (even with the odd case that someone is rushing to the hospital).  Moral action is evaluated in line with principles of behavior– a kind of virtue ethics, instead of a deontological or consequentialist one.

Rationality in Philosophy

In philosophy, 'rationalism' describes a belief in the supremacy of reason– reasoning and logic are the primary way we come to knowledge.  Kant suggested that there are analytic propositions which are true solely by virtue of semantics, like 'bachelors are unmarried', and early rationalists typically stood in opposition to empiricists, in their belief that principles of logic exist outside of experience and don't necessarily require empirical data to support them.  

It's important to draw some distinctions here in philosophy where (tacitly) empiricism and rationalism stand in contradiction.  An empiricist might say something like 'art is valuable because we perceive it as valuable'– you have to trust your perceptions first before you construct logic and argue from it.  A rationalist might say something like 'there is no articulation from the first principles of reason why art is valuable'– in this construction, reasoning about the value of life, emotion, positivity, etc is elevated above perceptual experience.

The modern intellectual world has drifted towards rationalism– we don't trust our perceptions (after all, we're full of cognitive biases and easily manipulated), and when push comes to shove we are nihilistic (nothing has provable meaning and therefore art certainly doesn't).  We might enjoy art, but we treat that enjoyment with suspicion; intrinsically meaningful pursuits are not in-and-of-themselves meaningful.  

I think it's pretty hard, however, to argue that pure reason or pure logic exists without empirical grounding– rational thought and abstraction follow from empirical experience.  If this is the case, it's completely illogical to apply the empirically derived rules of rationality– the subset of empirical experience that follows simple rules that we use to model the workings of objective reality– to the broader set of subjective  empirical experiences.  If we start by trusting our empirical experience, we should trust all of it.

Anti-rationalists typically reject the application of rational principles to human experience or behavior.  The idea that we can live happily in line with rational ideals, or that rationalism is good for the psyche, is a major point of critique.  

Regardless of the truth of rationalism (i.e. art has no value, in this example), we certainly must operate as if it does.  The more rationally you try to act the more you fight against your nature.  Few have put it more powerfully and succinctly than Dostoevsky in Notes from the Underground:

In short, one may say anything about the history of the world--anything that might enter the most disordered imagination. The only thing one can't say is that it's rational. The very word sticks in one's throat. And, indeed, this is the odd thing that is continually happening: there are continually turning up in life moral and rational persons, sages and lovers of humanity who make it their object to live all their lives as morally and rationally as possible, to be, so to speak, a light to their neighbours simply in order to show them that it is possible to live morally and rationally in this world. And yet we all know that those very people sooner or later have been false to themselves, playing some queer trick, often a most unseemly one. Now I ask you: what can be expected of man since he is a being endowed with strange qualities? Shower upon him every earthly blessing, drown him in a sea of happiness, so that nothing but bubbles of bliss can be seen on the surface; give him economic prosperity, such that he should have nothing else to do but sleep, eat cakes and busy himself with the continuation of his species, and even then out of sheer ingratitude, sheer spite, man would play you some nasty trick. He would even risk his cakes and would deliberately desire the most fatal rubbish, the most uneconomical absurdity, simply to introduce into all this positive good sense his fatal fantastic element. It is just his fantastic dreams, his vulgar folly that he will desire to retain, simply in order to prove to himself--as though that were so necessary-- that men still are men and not the keys of a piano, which the laws of nature threaten to control so completely that soon one will be able to desire nothing but by the calendar. And that is not all: even if man really were nothing but a piano-key, even if this were proved to him by natural science and mathematics, even then he would not become reasonable, but would purposely do something perverse out of simple ingratitude, simply to gain his point. And if he does not find means he will contrive destruction and chaos, will contrive sufferings of all sorts, only to gain his point! He will launch a curse upon the world, and as only man can curse (it is his privilege, the primary distinction between him and other animals), may be by his curse alone he will attain his object--that is, convince himself that he is a man and not a piano-key! If you say that all this, too, can be calculated and tabulated--chaos and darkness and curses, so that the mere possibility of calculating it all beforehand would stop it all, and reason would reassert itself, then man would purposely go mad in order to be rid of reason and gain his point! I believe in it, I answer for it, for the whole work of man really seems to consist in nothing but proving to himself every minute that he is a man and not a piano-key! It may be at the cost of his skin, it may be by cannibalism! And this being so, can one help being tempted to rejoice that it has not yet come off, and that desire still depends on something we don't know?

The Lever Problem

Most people are familiar with Harvard's late B.F. Skinner– one of the pioneers of modern behaviorism– because of his Skinner Box experiments.  This technique houses small animals in a box with a lever, with rewards appearing on different schedules (sometimes reinforcing the lever pushes, and sometimes not) to see how rewards reinforce behaviors.  Famously, intermittent variable rewards cause animals to press the lever most frequently.  These reward structures are what we find in slot machines and gambling, as well as the design of social media websites.

A famous critique of this result came with the 1978 'Rat Park' experiment.  The researchers behind this test suggested that previous experiments on highly addictive rewards (in which pigeons and rats would voluntarily drink morphine-laced water until they died) missed a crucial component – these animals were isolated and caged in a way that would promote drug addiction.  The Rat Park researchers believed that Skinner's drug addiction was not because drugs had been introduced to the animal environment, it was because normal social contexts had been removed.  They showed that rats presented with the same morphine rewards, but in a normal context (a larger, shared cage with other rats where they could reproduce), accessed the morphine rewards significantly less.

The specific results of the Rat Park studies are quite controversial despite their fame – the original study has failed to replicate consistently and was passed over by more prestigious journals because of serious methodological errors.   It's unlikely that the damning results they report are actually accurate.  However, a recent paper in the Journal for Reproducibility in Neuroscience argues that though the specific findings are not true, conceptually it has withstood the test of time.

For example, Lee Robin's 1974 study of Vietnam War veterans showed that, based on random drug tests, 10% abused narcotics before the war and 11% after the war, while that number skyrocketed to 43% while deployed (34% of those being heroin users).  The incredible low rates of heroin recidivism after use in Vietnam is truly remarkable (only ~1% of veterans re-addiction upon return). A 2017 follow-up study suggested that this result has much more to do with social and psychological factors (citing disapproval from family, legal troubles, fear for health, and fear of addiction) instead of access (most veterans reported that it was easy to obtain heroin in their area, and 10% tried heroin upon return even though only 1% continued).  If we just consider those that had easy enough access to heroin and high enough motivation to use it again, a 1-in-10 re-addiction rate for these high risk, re-exposed users is astounding.  Heroin is a potent drug.

Desperate People Push Levers

If you give desperate people a lever, they will push it.  It's like presenting a person in serious pain with a button to control their morphine.  When morphine addiction inevitably starts to skyrocket, taking the morphine away doesn't solve the underlying problem– and people suffering from pain will be on the market for the closest morphine-replacement they can find.

The correct, more difficult way to solve the 'lever-pushing' problem is to address the underlying desperation.  Removing all Facebook-like levers is not realistic, nor does it address the desire for a Facebook lever.  There will (and should) be democratic, social technology in the marketplace.

Regulation seeks to remove or shape levers without considering the underlying socio-psychological landscape of the individual.  It covers the symptom, but doesn't fix the problem.  It obscures the true causes.  Regulation is an analgesic.

Addiction is Real

Addiction is complex.  There are many things that factor into our susceptibility to a given lever-reward– the genetic predisposition of the person, their underlying psychological needs, the broader environment, the barriers of access to a given lever, and whether the lever exists as an option at all.  

In the case of social media, it is very hard to regulate properly without threatening either a useful underlying technology, or an embodiment of that technology that is good and useful in other contexts.   That's not to say we don't have an interface problem with social media– right now, we're forced to carry it with us everywhere we go to engage with the world, and we should have a lot more agency over how we interface with our technology.  However, the effort we spend shaping levers and tweaking our barriers to access them ignores a more severe and important underlying problem.  

Those with intrinsically meaningful lives outside of technology are rarely seduced by it.  In my experience at the MIT Media Lab (and famously in the example of Steve Jobs or Bill Gates), those that understand the influences of technology minimize its role in their lives, successfully.  I've been amazed at how many of my friends at the one of the most technologically-focused labs in the world live minimalist, anti-tech lifestyles at home.

But the problems of social media– whether its a superficial stand-in for real social connection or it's a political machine that radicalizes deeply-held, identity-driven ideologies– are symptoms much more than causes.  

Our sense of intimacy, community, and trust has largely dissolved in post-industrial, post-WWII society– a trend which predates the internet.  Our desire for structured meaning, belief, and belonging– previously the domain of religion and war and local community– have been annexed by sound-byte politick.

These deep and real human needs will continue to be met somehow.  Unless we look towards individual psychology and address them at their core, we'll find ourselves regulating lever and lever away in a game of whack-a-mole.  In the process, we risk damaging the real value that these services provide underneath their perversions.  

The pathology of the modern condition is to feel isolated, lonely and tuned-in; comfortable, satiated, and redundant; nihilistic, disillusioned, and deeply ideological.... with access to social media.  Only one of those is the real problem.  We need to stop focusing so much on the lever, and take a much closer look at the life of a rat in its cage.

Statistically, this study is simple– it's based on a trustworthy and large sample size, and basic statistical tests.  The paper only has one figure.  Despite that, its remarkably difficult to contextualize.   This essay is a deep dive into the numbers– a gut check of the data, and an examination of the common sense inferences we can actually make based on what they report.

The Basics

The study includes 4 groups of ~175,000 people each– 2 intervention groups matched with 2 control groups.  Subjects in the intervention groups had either 'positive' or 'negative' posts removed from their newsfeeds, judged based on whether they contain a positive or negative word listed in the 'LIWC'.  

Not all of a subject's emotional posts were removed, though– for example, in the positive condition, subjects experienced between 10% and 90% of the positive newsfeed posts removed. This means the 'average' intervention removed half of someone's positive or negative posts.  

Over the course of a week, the study measured whether these changes in newsfeed content would alter the number of positive or negative words a subject subsequently used themselves when posting status updates.  Changes in word usage should prove that what you see online affects your mood– emotional contagion.

The study includes some interesting basic statistics about facebook usage. Based on their analysis of 3 million posts, an average post is ~41 words.  47% of posts contain a positive word and 22% contain a negative one, so the average positive post has 2.9 positive words and the average negative post has 2.8 negative words.  The differing rates of emotional content means positive group interventions are more invasive– deleting half of your positive posts replaces 23% of your news feed, while deleting half of your negative posts replaces only 11%.  

The Results

The major results are in the figure below.  We see that an average person uses ~5.2% positive words and ~1.75% negative words (dark blue controls).  

It turns out that people use fewer words when the content they see is less emotional.  By how much? 0.3% fewer words used if negative posts are (on average) half removed, and 3.3% fewer words in the positive case.

These differing rates means we can't compare group-level word averages–  since the strength of the intervention varies across subjects, we'd diminish the contribution of individuals who show the greatest effect (a more powerful intervention means fewer emotion words seen, and thus fewer words posted/counted).  

To analyze this in a way that maximizes the likelihood of finding an effect, the authors instead train a small weighted linear model to predict the likelihood that a subject will use a positive or negative word in their post that is weighted by the likelihood that the subject had a given emotional post removed.  The values we see in the plot above consider intervention subjects that had 90%(!) of their posts removed as 9x more important than people with 10% removed.

Thus, these results are skewed to represent the effect of closer to the weighted average response of  ~60%* of the positive or negative posts removed, if we assumed the effect is linear.  

But of course we shouldn't expect that.  Having a few positive posts removed probably does very little to you, as you'd still see a large amount of positivity; on the other hand, we'd expect a pretty drastic effect if nearly all of your positive posts are removed.  It's unlikely the relationship is a simple linear mapping.  Because we weigh a 90% user so much more, this analysis really over-emphasizes the effect for people with drastic interventions– it's likely more representative of the experience of someone with 65-75% of their posts removed.

The reported effect sizes heavily emphasize users who received a drastic intervention.  It's almost impossible to know the relationship of this effect size with the intensity of the intervention, though a measurable difference in word use exists.  Unfortunately, demonstrating that a difference exists isn't particularly meaningful– we really care to know how much of an effect occurs at what intensity of intervention and for whom.

An Unusual Discrepancy

Digging further into the data, we notice overall reported rates of 3.6% positive words and 1.6% negative words, whereas per person results in the figure show 5.2% of the words are positive and 1.7% are negative.    

I initially thought there might be an error in the study (3.6% + 1.6% = 5.2%; it looks suspiciously like the positive word results also include negative words).  After some back and forth with the authors, they suggested an alternative, unmentioned explanation– an underlying relationship where individuals who use more words use significantly fewer positive words.  

This has some serious implications for how we interpret the study.

I was able to roughly corroborate these numbers with other literature.  One other study reported, for N=150,000, positive LIWC rates of 3.9% (SD=2.0%) and 1.8% (SD=1.1%) negative rates in status updates overall; in another very small study (N=29) positive LIWC emotion word percentages range from 2% to 57% (average of 10%) per person, and negative word percentages from 0% to 17% (average of 4%).  Since this analysis was over several weeks, we can expect slightly higher variability in the shorter Facebook study.  

Based on some other literature from the same time period (1, 2), we know that the number of Facebook posts per user follows a power law distribution:

It's unclear what (if any) relationship there is between number of posts and length of post– I couldn't find any data about this.  Regardless, it seems reasonable to assume that we'll still end up with a power law distribution in words per person as we do for posting frequency.

Given this distribution, for the overall positive word rate to be 3.6% with a per person word rate at 5.2%, the vast majority of people are posting very few, very positive posts.  Most people post rarely, and it seems reasonable to imagine that most of their posts have to do with celebrations or special events.

In the below cohort study based on (predominantly young, black, and urban) hospital patients, we can see some clear trends that support the idea that positive words are used by people who post infrequently, who make up the vast majority of people (despite the unusual hospital-focused sample).  Patients with depression were significantly more likely to post more frequently (38 vs 22 times on average, N=~150, 550), a correlation which has been corroborated in studies outside of hospitals as well.

Contextualizing the Data: What Does it Mean?

In the above sections we established a few key things:

(1) We have baseline positive and negative word use rates of 5.2% and 1.7% per person.  In the case of positive words, we know that this 5.2% per person number is heavily influenced by highly positive, infrequent posters who are most representative of the 'typical' user.  These users' positive words are probably congratulatory and unrelated to emotional state– though there is a small increase in negative words when positive posts are reduced, so some effect cannot be attributed to this explanation.  The averages obscure trends in real underlying behavior of different kinds of users.

(2) The analysis shows very small changes in word use behavior of 0.2 to 0.15%, but what this means for a typical user over intervention severity is unclear.  The technique is heavily weighted to represent a drastic intervention– something roughly like removing 70% of emotion posts from a person's feed.

If we put aside that these small effects are likely a result of infrequent congratulatory or conciliatory posts in response to personal news, we can focus on the smaller secondary effect (a.k.a. fewer positive posts sparking more negative words and vice versa).  While these small changes can be explained as a very subtle sort of social mirroring (fitting in with group behavior), they also could perhaps capture some real change in underlying emotional state.  Do they?

Does Your Positive Word Count Reflect Your Positive Emotions?  

Based on this study from 2015 (N=200), increased LIWC negative word use reflects real anxiety, depression, and stress, while positive word use is uncorrelated with psychological indicators.

This correlation is strongest in young people; younger people are more self-disclosing on social media and use more emotion words, so their linguistic features might be more relevant.  Older people are more prone to 'image management', which might also explain a decoupling between positive words and underlying emotional states.  Other studies back up the notion that positive words correlate with image management and not emotional state.

"Do Facebook Status Updates Reflect Subjective Well-Being?"– a study from 2015– shows that for 1,100 participants, subjective wellbeing and the LIWC score are only related when users show evidence of negative language in the last 9 months.  If you look at the graph below, you can see that just looking at word usage over the most recent month or two is not at all predictive of subjective well-being; data over the last 8-10 months becomes a meaningful indicator, and adding data beyond 10 months reduces the correlation.   While it is a real correlation, it is still a very, very weak one (<0.2).  Once again, positive word use is simply not meaningfully predictive at all.

Another study from 2018, "Does Counting Emotion Words on Online Social Networks Provide a Window Into People’s Subjective Experience of Emotion? A Case Study on Facebook", showed no relationship between LIWC word percentage and self-reported affect; however, human judges reading the posts were able to predict affect poorly but meaningfully (correlations around 0.15.) They summarize their results (for 185 college students) by quoting Pennebaker et al (2003):

Virtually every psychologically based text analysis approach has started from the assumption that we can detect peoples’ emotional states by studying the emotion words they use... [but] in reviewing the various word use studies, it is striking how weakly emotion words predict people’s emotional state... taken together, it is our sense that emotion researchers should hesitate before embarking on studies that rely exclusively on the natural production of emotion words. (p. 571)

Finally, "Emotional States vs. Emotional Words in Social Media" (2015) found similar weak (~0.15) correlations between affective ratings and LIWC scores across 515 Facebook users:

...although we found a reliable correlation between negative affect on the PANAS and negative sentiment as measured by LIWC for Facebook status updates, at best the LIWC scores account for 4.2 percent of the variance in one’s reported negative affect.

Their analysis corroborates that 6 months of data is required, and suggests that this kind of analysis really only makes sense for a small subset of self-reported 'highly emotionally expressive' people.

The conclusion is clear– in no way are changes in a week's worth of LIWC emotion word data indicative of any underlying emotional changes in Facebook users.  Even over long time scales, positive words seem meaningless as a predictive tool of underlying emotional state.

Finally

The Facebook Emotion Contagion study shows incredibly small changes in emotion word rates from an invasive intervention.  These changes seem to be explained largely by common usage patterns (a typical user will post an infrequent, congratulatory post on a positive personal announcement); for the unaccounted difference that remains, there is substantial evidence refuting the idea that LIWC word choice captures anything meaningful about a user's emotional state.  For even the most severe manipulations, we cannot trace a causal pathway through user emotional.

For such a simple study, it is remarkably hard work to contextualize for typical Facebook users.  The paper uses statistical techniques that increase the probability of finding an effect at the expense of obscuring how large of an effect occurs at what intensity of intervention and for whom.  The point estimates we're given are reweighted by intervention type and averaged over an uneven distribution of users.

That makes our job– to contextualize the meaningful implications– significantly harder.  Effect size matters.  Missing this nuance not only can create a media firestorm over a totally benign intervention, it can also undermine the scientific value of the research.

*  ∫x*p(x) from .1 to .9, where p(x) = x / (∫x from .1 to 0.9) to normalize it so it's a probability distribution with area 1.

The laissez faire attitude around Near IR is not totally unwarranted–  IR diodes do at least partially deserve their innocuous reputation.  IR is what we think of as heat, and we get a lot of it from the sun (the majority of the energy from the sun at the earth's surface is IR).  From what remains, ~40% of the sun's energy is visible light, and only a couple percent is UV (the actually dangerous stuff that gives you cancer and contributes to macular degeneration).  UV is typically the one we really need to worry about.

While we get quite a bit of IR radiation in the ambient world, we do need to worry about how it interacts with our eyes.  Our eyes have a few parts– the outer part is the cornea, which envelopes the entire eye; under the cornea, there is a little pocket of fluid called the aqueous humor which covers the pupil and the pigmented iris that surrounds it. Within the pupil is a lens that will focus light onto the retina.  Each of these parts can be damaged, and will have a different mode of damage.  

Causes of Concern

Increased IR exposure does put you at increased risk of cataracts.  Cataracts are pretty common (68% of people over 80 have them in the US), and they occur when the lens of the eye gets cloudy.  IR is believed to contribute to their formation if the lens of the eye absorbs the IR light and heats up.  In 'Infrared radiation and cataract II. Epidemiologic investigation of glass workers', we find that folks working in the glass industry for 20 years have >10 times the risk of cataracts.   Similar studies have been done on steel and iron workers.

It is also possible to damage the retina of the eye with IR radiation, though the data here seems less clear.   Other wavelengths are more tightly coupled to age related macular degeneration– near IR exposure may actually improve retinal function as you age.  Based on a recent nature paper entitled 'Does infrared or ultraviolet light damage the lens?', it seems that photochemical damage is unlikely, and we really only need to worry about thermal effects would lead to retinal damage.   This means the typical relationship for photochemical injury– where damage is integrated over intensity/duration– doesn't apply.  Instead, thermal damage only happens when tissue heats beyond a certain point.

This can happen with a large burst of coherent light (much like a visible laser).  This is really only a concern for the nearest of the near IR, because these wavelengths are close enough to visible wavelengths to actually make it through the lens of the eye to the retina (as you get higher wavelengths, they simply get absorbed by the cornea and lens and don't pass through).  Of course, the lens of the eye focuses light on the retina, and this can have a hugely multiplicative effect on concentrated hot spots (focusing the power up to 100,000 times more than what would be seen at the cornea).  This focusing works exactly like visible light, and the distance of the source is important to how focused it will be.  From 'Class I infrared eye blinking detector' we find the following:

In case of a point-type and diverging beam source, as a LED, the hazard increases with decreasing distance between the beam source and the eye. This is true until distance is greater than the shortest focal length. Thus for distance less than the shortest focal length there is a rapid growth of the retinal image and a corresponding reduction of the irradiance, even though more power may be collected.

So it turns out there is actually a complicated relationship beyond just distance to irradiance at the retina, which has to do with the focal effects and optics of the lens.  

The paper 'Eye safety related to near infrared radiation exposure to biometric devices' suggests that IR-induced warmth on the outer eye will cause pain and blinks to conduct heat away, and that the main thing we should worry about for near IR is retinal exposure because it is conducted like visible light to the retina, but doesn't cause a blink reflex like bright visible light would.  This is frequency dependent, as we can see from the following graph:

the region we care about actually has quite varied behavior; on the low side (760nm) around 80% of the power makes it to the retina, and almost none is absorbed by the cornea or lens; as we move higher, we see less than 50% makes it to the retina, with almost 50% split between the cornea and the lens.  We'll see when we calculate 'retinal hazard', we weight the energy by a value that captures this transmittance– so the higher we go, the less we have to worry about the retina and the more we have to worry about the cornea and lens.  Where we should focus our efforts depends on the wavelength we choose.

Another analysis of cow eye parts shows how they absorb over wavelengths (cows have pretty similar eyes to us):

For the cornea, we care about temperature equilibrium under continuous exposure.  It turns out this is a complicated thing to understand and contextual, but we have a few interesting tidbits– the iris is very absorptive, the pupil is very dynamic (contracting from ~7mm in dark to ~1.6 mm in light), and blinks happen once every ~3 seconds for ~0.3 seconds (10% of the time our eye is closed!).  That's not factoring in the other main mechanisms governing temperature– blood flow in the eye, conduction through tissue, body temperature, and ambient temperature.  Ocular surface temperature can vary quite a bit depending on the weather!

Measurements

We care about power [W], which gets the name 'Radiant Flux' when we look at how much is delivered through an specific area, and 'Irradiance' [mW/cm^2] when we normalize by the area.  Here, when we talk about the irradiance (power/area at the eye), we've accounted for the distance between the source and the eye already– the power per area obviously drops as we move further away. If we'd rather measure power through an area in a way that is distant agnostic, we can also talk about the 'Radiance' [mW/cm²/sr] where a steradian [sr] is a 3D radian which looks like a spotlight cone– this tells us how much power is delivered per area out in one small angular cone from a point source.  The easiest way to think of this is that the area mm² per angle sr grows as we move away from the source, so we have our power averaged over the squared mm per cone.  Of course, we typically are interested in a frequency specific measurement for all of these quantities, so frequently they will be quoted normalized over a 1 nm band of wavelength (i.e. 'irradiance' per nm, which is still called 'irradiance').  

IR-radiation is anything above visible light in wavelength on the spectrum between 760 nm (or 0.76 um) and 1 mm (or 1000 um)  (remember, a higher/longer wavelength, in nm, means a slower frequency in Hz).  It's typically divided into IR-A, -B, and -C or Near, Mid, and Far, but be careful because these distinctions don't map perfectly to each other.  For the types of diodes and applications we care about, we'll be strictly in the shortest wavelength Near-IR/A range (760 nm-1400 nm).

In this range, the sun's irradiance at the earth's surface falls linearly from about 0.1 to 0.05 mW/cm²/nm, so we find ourselves in about 32 mW/cm² over that entire 760-1400 nm bandwidth; however estimates of IR background exposure outside (when you're not looking directly at the sun) are roughly 1 mW/cm².  

The final thing we need to understand before we move forward is 'angular subtense' (alpha), which is simply a way to describe how large something will be on the cornea (i.e., how large of a 3D cone described by angle alpha, in radians).  It describes the minimum image size on the retina that can be produced by focusing on the object– what we care about is how much the eye can help concentrate the power of incoming waves on a small area.  

See 'Location and size of the apparent source for laser and optical radiation ocular hazard evaluation' for a good review.  It's worth noting that the lenses in our eyes changes shape to focus at different distances (accomodation) in addition to the changes in angle between our eyes when we gaze at something close vs. far way (vergence), and rules are different for collimated or coherent light.  

Rules of Thumb for the Retina

In 'Eye Tracking Headset Using Infrared Emitters and Detectors' they calculated a retinal hazard threshold of 92 W/cm²/sr for 10 minute exposures.

The ICNIRP guidelines 'On Limits of Exposure to Incoherent Visible and Infrared Radiation' suggest for long duration exposure, we should be less than 190o W/cm²/sr for small sources and less than 28 W/cm²/sr for large sources (smaller sources will diffuse as the eye moves more easily).  The below plot shows between 6 and 60 W/cm²/sr depending on apparent size on the retina.

Regulation for the Retina

This formula is for retinal damage, based on the 'burn hazard effective radiance' for stimuli that don't come with a visual stimulus that would cause natural avoidance:

Where L(λ) is the average spectral radiance in a band (W/cm²/sr/nm) times the bandwidth range it's over, weighted by a unitless R function based on how much that frequency is transmitted to the retina.  We sum this over all the bands in the range of interest.

There are several worst case assumptions that go with this– a fully dilated pupil (7mm diameter), and irradiance measured at 20cm (ANSI Z136.1) or 10cm (IEC 60825-1) because this is the lower limit of eye accomodation, which means it is the closest you can get to the eye where the eye will focus the power on the smallest section of the retina (worst case, closer makes it blurred).  Notice the limit is a 'radiance' limit– that is, it assumes the worst case distance, and is simply the amount of radiated power in a given angular slice from the point source.  Alpha is the 'angular subtense' of the source and is taken as 0.011 rad if the apparent source size is small than that.

For us, our LED is roughly 1.5x2.5mm, which we'll call 2mm.  Let's do our basic math:

It's actually assumed the angular subtense increases over exposure time, as your eye moves and blurs the source around on the retina (which is good if we're trying not to damage it, hence the lower limit).  Given the above alpha, the target is 0.6/0.02 = 30 W/cm²/sr.  

The R values come from here (note there is an equation in the caption):

As we saw above earlier, the amount of energy that gets absorbed by the cornea and the lens at this frequency is actually quite a lot, so we have an R of ~0.33.

Now we need some idea of the Source Radiance over our bandwidth.  Now we need to translate the following (from the datasheet) into power:

Unfortunately this is the only piece of information we have, other than that we can set the power through the diode with a current limiting resistor.  We've set ours to about 25mW through the diode of electrical power.  Current IR LED technology has a peak 'Wall-Plug Efficiency' of 40-50% (electrical to optical power), so we'll assume that our LED is doing really well and has an efficiency of 50%– and thus an optical power of around 12.5mW.

If we take the worst case (most intense) angle above, +-10 degrees has an average intensity of 0.98, and appears to capture about 18.5% of the total radiated power (Calculated by looking at average intensity across each 10 degree band).  So we'll guess that, right in the middle of the beam, we get around 2.5mW over a 20 degree angle (0.35 radians).  This could be calculated more accurately using Lambertian assumptions (LEDs typically have a well defined emission pattern), but this back of the envelope should be fine.    

Step 1 is to turn that 2D cross section to a 3D cone steradian– not a trivial task.  Stack Overflow and Wikipedia tell us that for angle 2θ (θ=0.175 radians for us):

So we get 0.096 sr.  Our 2.5mW thus gives 26.05 mW/sr.  We then divide this by the size of our radiating source (4 mm² = 0.04 cm²) because it's not a perfect point source, so we need to account for its area (if this is confusing, take a look at the light bulb drawing on this website).  We get 650 mW/cm²/sr.

This value is assuming all of the power across all frequencies that the diode is converting to light (its entire bandwidth).  If we want to convert this into a bandwidth agnostic number, we have to divide out our expected bandwidth (probably on the order of 20-50nm), but that would be silly since we really just care about total delivered power in the equation above.  If we apply our R value, we get a weighted 650*0.33 = 215 mW/cm²/sr over our entire bandwidth.  

That 0.215 W number is quite a ways away from the 30W limit we calculated; keep in mind as well that we used worse case metrics for this as well (a fully dilated pupil, from the worst case focal distance, right in the hot spot of the LED).  In reality we should expect something smaller; it seems we're good to go for unlimited time as far as the retina is concerned.

Rules of Thumb for the Cornea/Lens

Roughly, background IR from sun exposure at the eye is ~1 mW/cm², though we apparently get between 20-40 mW/cm² on our skin.

Occupationally, we see rates of 15-180 mW/cm² daily for glass blowers at the eye, and 200-600 mW/cm² for metal workers.  Over a decade lead to extreme increase in cataract risk.

In 'Eye Tracking Headset Using Infrared Emitters and Detectors' they set their safety limit at 14.8 mW/cm² for 10 minute exposures.  (they apparently use 5 LEDs, as well as the QRE1113).

Regulations for the Cornea/Lens

The Cornea and Lens area are probably more of a concern, because that's where the cataracts occur, these structures are moderately absorptive at these frequencies, and the sun background exposure typically doesn't get very high.

The International Commission of Non-Ionizing Radiation Protection (ICNIRP)/ IEC-62471 suggests ocular exposure should not exceed 10 mW/cm² for chronic exposure, though around 100 mW/cm² is the suggested tolerance for IR lasers– these recommendations are to protect the cornea.  The formula is:

We can get at the basic rule of thumb here– our diode puts out 12.5 mW from a 2x2mm source– that's ~312.5 mW/cm² directly at the source (if we stuck it right on our eyeball).  It's probably ill-advised to do this, even if it would only be heating a very small part of the eye.

for our 2x2 source, let's go back to our most intense direct emission, which was within the 20 degrees directly in front of the diode.  We saw this captures about 20% of the radiated power, or 2.5mW.

So we can solve the minimum safety distance for our example with the most concentrated part of the beam (2.5mW source power radiating at a 10 degree angle from a 2x2mm) by solving (sqrt(2.5/10)-.2)/(2*tan(10 deg)).  Be careful with units– everything should be in cm since our target value uses them.

To hit the 10mW/cm² safety target, we need to be ~8.5 mm away.  Another way to do this calculation is based on the beam divergence that includes 63% of the power, but assume it includes 95% of the power.  That gives a 70 degree beam at 12.5mW and a safe distance of 6.5 mm.

For a sense of scale, your eyelid itself is around 1 mm thick, and eyelashes are longer than 10 mm on average.  Based on our measurements of eye distance from the sensor, we should be far enough away not to worry (and these calculations assume really the worst case– very close, very direct and concentrated power, your eye isn't moving around, plus a significant overestimates of concentrated power) and of course the recommendations have margin.  Moreover, power falls off with distance squared, so any extra distance adds an exponential safety margin.

Moreover, the real place we're concerned about is the lens, as well, which is further from the diode and unlikely to spend time in continuous direct exposure.  These recommendations are made with the assumption that the irradiance is constant in the space, bathing the whole eye– obviously the eye will be able to conduct heat away in our case more easily because only the nearest part of the eye will experience the peak irradiance, and that part is still under the safety margin for the geometry we've built.

Other People's Work

'Eye Tracking Headset Using Infrared Emitters and Detectors' set their safety limit for 10 minute exposures; they apparently use 5 LEDs together, which seem to have all been QRE1113s.

'DualBlink' uses the QRE1113 set at 20mW.

In 'Class I infrared eye blinking detector' they do a thorough analysis on their system, which includes a Agilent HSDL9100-21 IR-transmitter and receiver (940nm, 50nm bandwidth, 1.8mm source, apparent source size of 0.8mm, 26 degree beam divergence, which is the area for 63% of power).  They directly measured 7.6 uW of Radiant flux in a standards compliant way, and using the strictest standards designed it to be operational for 8 hours a day with a 1kHz sampling period; they use IEC 60825-1, which treats Lasers and LEDs the same and thus dramatically over-estimates the risk.

According to Eye safety related to near infrared radiation exposure to biometric devices:

Eye safety is not compromised with a single LED source using today's LED technology, having a maximum radiance of approximately 12 Wcm−2 sr−1 [12]. Multiple LED illuminators, however, may potentially induce eye damage if not carefully designed and used.

Best References

ICNIRP GUIDELINES ON LIMITS OF EXPOSURE TO INCOHERENT VISIBLE AND INFRARED RADIATION.

EHS Document on Light and Near-Infrared Threshold Limit Values.

Eye safety related to near infrared radiation exposure to biometric devices.

Class I infrared eye blinking detector.

Incorporating Persistent Firebase Authentication

First we'll set up our project:

npx react-native init ReactNativeTestFirebase
cd ReactNativeTestFirebase
npm install --save @react-native-firebase/app

open the .xcworkspace project.  Click on the main project; change the bundle identifier and name to something nice.  Copy the bundle name.  Change signing and capabilities to our personal team.

create app on firebase named 'WatchV1App'.  Now add an iOs app, copy the bundle identifier and register the app.  Download the associated file and drop it into the xcode project folder where the Info.plist file is, selecting all targets.

In firebase, go to authentication, click get started, enable 'anonymous'.

Go to ios/WatchV1App/AppDelegate.m, at top add

#import <Firebase.h>

and at the beginning of didFinishLaunchingWithOptions:(NSDictionary *)launchOptions add

if ([FIRApp defaultApp] == nil) {
    [FIRApp configure];
  }

on the next line (first line of the method after the opening bracket).

Now we'll install the firebase tools we need to use, firestore and auth:

cd ios
pod install --repo-update
cd ..
npm install --save @react-native-firebase/auth
npm install --save @react-native-firebase/firestore
cd ios && pod install 
cd ..
npx react-native run-ios

Now we're setup.

We'll replace our App.js file as follows:

/**
 * Sample React Native App
 * https://github.com/facebook/react-native
 *
 * @format
 * @flow strict-local
 */

import React, {useState, useEffect} from 'react';
import {
  SafeAreaView,
  StyleSheet,
  ScrollView,
  View,
  Text,
  StatusBar,
} from 'react-native';

import {
  Header,
  LearnMoreLinks,
  Colors,
  DebugInstructions,
  ReloadInstructions,
} from 'react-native/Libraries/NewAppScreen';

import auth from '@react-native-firebase/auth';

auth()
  .signInAnonymously()
  .then(() => {
    console.log('User signed in anonymously');
  })
  .catch(error => {
    if (error.code === 'auth/operation-not-allowed') {
      console.log('Enable anonymous in your firebase console.');
    }

    console.error(error);
  });


function App() {
  // Set an initializing state whilst Firebase connects
  const [initializing, setInitializing] = useState(true);
  const [user, setUser] = useState();

  // Handle user state changes
  function onAuthStateChanged(user) {
    setUser(user);
    if (initializing) setInitializing(false);
  }

  useEffect(() => {
    const subscriber = auth().onAuthStateChanged(onAuthStateChanged);
    return subscriber; // unsubscribe on unmount
  }, []);

  if (initializing) return null;

  if (!user) {
    return (
      <>
      <StatusBar barStyle="dark-content" />
      <SafeAreaView>
        <ScrollView
          contentInsetAdjustmentBehavior="automatic"
          style={styles.scrollView}>
          <Header />
          <View style={styles.body}>
            <View style={styles.sectionContainer}>

        <Text>Error connecting to Firebase</Text>

        </View>
        </View>
      </ScrollView>
      </SafeAreaView>
      </>
    );
  }

  return (
      <>
      <StatusBar barStyle="dark-content" />
      <SafeAreaView>
        <ScrollView
          contentInsetAdjustmentBehavior="automatic"
          style={styles.scrollView}>
          <Header />
          <View style={styles.body}>
            <View style={styles.sectionContainer}>

            <Text>Welcome {user.email}</Text>

        </View>
        </View>
      </ScrollView>
      </SafeAreaView>
      </>
  );
}

const styles = StyleSheet.create({
  scrollView: {
    backgroundColor: Colors.lighter,
  },
  engine: {
    position: 'absolute',
    right: 0,
  },
  body: {
    backgroundColor: Colors.white,
  },
  sectionContainer: {
    marginTop: 32,
    paddingHorizontal: 24,
  },
  sectionTitle: {
    fontSize: 24,
    fontWeight: '600',
    color: Colors.black,
  },
  sectionDescription: {
    marginTop: 8,
    fontSize: 18,
    fontWeight: '400',
    color: Colors.dark,
  },
  highlight: {
    fontWeight: '700',
  },
  footer: {
    color: Colors.dark,
    fontSize: 12,
    fontWeight: '600',
    padding: 4,
    paddingRight: 12,
    textAlign: 'right',
  },
});

export default App;

This now will connect with a persistent anonymized user ID; when sign in occurs and authenticates we get onAuthStateChanged() called.   We should be able to see ourselves in the authorization section of firebase after we run the app.

Set up Firestore

Now we will set up 'conditions' and 'events' collections.  These will be creatable by an anonymized but logged in user; they'll contain an 'id' field that matches their logged in key; and they will only be readable if the id field is their own.  This will partition data by user.

Firestore is nice in that it is schema-less; we can simply push arbitrary json blobs to it any collection of documents.

We start in the firestore UI; we create a datastore in a central US region in 'production' mode.  we then 'start a collection'.  I'll make one called 'conditions', and it will have some fake data (autoid, timestamp:timestamp, temperature/humidity/lux/whitelux numbers, and uid string). For the uid string, I'll copy the UID from the authenticated user section.  I'll also make a conditions document with fake data and a different uid so we can check access.

We'll do a similar thing for 'event's.

Next we'll go to rules.  We want to add rules for all documents; we want to be able to read and create if the uid of the data equals the uid of the auth, otherwise nothing is allowed (no 'update', and write gives delete, create, and update permissions.  Read can be broken into get and list (ability to access one document at a time vs list all of them)).

The default rule will match any document in our database (this is a recursive matching syntax).  We will simply update this rule as follows:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow create:
        if request.resource.data.uid == request.auth.uid;
      allow read:
      	if resource.data.uid == request.auth.uid;
      allow update, delete: 
        if false;
    }
  }
}

This should make it so only create/read are allowed, and users can only read/write data with their own UID (assigned anonymously with the session).

Now let's edit our app to be able to read and publish data.

/**
 * Sample React Native App
 * https://github.com/facebook/react-native
 *
 * @format
 * @flow strict-local
 */

import React, {useState, useEffect} from 'react';
import {
  SafeAreaView,
  StyleSheet,
  ScrollView,
  View,
  Text,
  StatusBar,
  Button,
} from 'react-native';

import {
  Header,
  LearnMoreLinks,
  Colors,
  DebugInstructions,
  ReloadInstructions,
} from 'react-native/Libraries/NewAppScreen';

import auth from '@react-native-firebase/auth';
import firestore from '@react-native-firebase/firestore';

auth()
  .signInAnonymously()
  .then(() => {
    console.log('User signed in anonymously');
  })
  .catch(error => {
    if (error.code === 'auth/operation-not-allowed') {
      console.log('Enable anonymous in your firebase console.');
    }

    console.error(error);
  });

const conditionsCollection = firestore().collection('conditions');
const eventsCollection = firestore().collection('events');


function App() {
  // Set an initializing state whilst Firebase connects
  const [initializing, setInitializing] = useState(true);
  const [user, setUser] = useState();
  const [conditionsArray, setConditionsArray] = useState([]);
  const [eventsArray, setEventsArray] = useState([]);

  // Handle user state changes
  function onAuthStateChanged(user) {
    setUser(user);

    conditionsCollection.where("uid","==", user.uid).get().then(querySnapshot => {
      let cArray = [];
      querySnapshot.forEach(doc => {
        cArray.push(doc.data());
      });

      setConditionsArray(cArray);

      eventsCollection.where("uid","==", user.uid).get().then(querySnapshot => {
        let eArray = [];
        querySnapshot.forEach(doc => {
                eArray.push(doc.data());
        });

        setEventsArray(eArray);

        if (initializing) setInitializing(false);

    }, error => {console.log(error.code);});


    }, error => {console.log(error.code);});
  }


  async function addEvent(timestamp, type, data){
    console.log('sending event for user ' + user.uid);

    let eventdoc = {
        uid: user.uid,
        timestamp: timestamp,
        type: type,
        data: data
    };

    setEventsArray([...eventsArray, eventdoc]);
    await eventsCollection.add(eventdoc);

  }

  async function addCondition(timestamp, temp, humd, lux, wlux){
    console.log('sending condition for user ' + user.uid);

    let conditiondoc = {
        uid: user.uid,
        timestamp: timestamp,
        temperature: temp,
        humidity: humd,
        lux: lux,
        whitelux: wlux
    };

    setConditionsArray([...conditionsArray, conditiondoc]);
    await conditionsCollection.add(conditiondoc);
  }

  function addRandomEvent(){
    let ts = new Date();
    addEvent(ts, 'TX_EXAMPLE_TYPE', 2);
  }

  function addRandomCondition(){
    let ts = new Date();
    addCondition(ts, Math.random(), Math.random(), Math.random(), Math.random());
  }

  async function getAllConditions(){
    return await conditionsCollection.get();
  }

  async function getAllEvents(){
    return await eventsCollection.get();
  }

  useEffect(() => {
    const subscriber = auth().onAuthStateChanged(onAuthStateChanged);
    return subscriber; // unsubscribe on unmount
  }, []);

 const conditionItems = conditionsArray.map((conditions) =>
       <Text key={conditions.timestamp + conditions.uid}>
        {conditions.timestamp.toString()} {"\n"} {conditions.temperature} {"\n\n"}
       </Text>  );

  return (
      <>
      <StatusBar barStyle="dark-content" />
      <SafeAreaView>
        <ScrollView
          contentInsetAdjustmentBehavior="automatic"
          style={styles.scrollView}>
          <Header />
          <View style={styles.body}>
            <View style={styles.sectionContainer}>

            {user ?
                <Text>Welcome {user.uid}</Text> :
                <Text>User not logged in</Text>
            }
            {initializing ?
                <Text>initializing</Text> :
                <Text>initialized</Text>
            }

        <Button
        title="Send Random Condition"
        color="#010101"
        onPress={addRandomCondition.bind(this)}
        />

        {conditionItems}

        </View>
        </View>
      </ScrollView>
      </SafeAreaView>
      </>
  );
}

const styles = StyleSheet.create({
  scrollView: {
    backgroundColor: Colors.lighter,
  },
  engine: {
    position: 'absolute',
    right: 0,
  },
  body: {
    backgroundColor: Colors.white,
  },
  sectionContainer: {
    marginTop: 32,
    paddingHorizontal: 24,
  },
  sectionTitle: {
    fontSize: 24,
    fontWeight: '600',
    color: Colors.black,
  },
  sectionDescription: {
    marginTop: 8,
    fontSize: 18,
    fontWeight: '400',
    color: Colors.dark,
  },
  highlight: {
    fontWeight: '700',
  },
  footer: {
    color: Colors.dark,
    fontSize: 12,
    fontWeight: '600',
    padding: 4,
    paddingRight: 12,
    textAlign: 'right',
  },
});

export default App;

We notice that *even when we are offline*, we log in as a user instantly.  When we are offline, it takes about 10 seconds for Firebase to timeout trying to connect to the actual server, and instead 'initialize' offline using the cache.  Data sent when we are offline is cached and makes it online when we get online; data 'sent' when we're offline before the cache is initialized is added to the cache seamlessly.

This will give the app user an anonymous ID that persists over time; it will log them into that ID even offline; it will allow you to send data even when offline, and will attempt to cache/persist some data when offline; it will give them create access to send data to the firebase server, and read access to their own data, which will be updated to the relevant state as soon as the user is authenticated.

Attempting to access data without the where("uid","==",user.uid) phrase will give an unathorized error, exactly as we want.

It's a nice, seamless experience that handles local caching, updating, user sessions, data privacy, and authentication without having to worry about online/offline status ourselves.

Querying Chronologically

In order to filter our returned values chronologically and just pull the most recent, we need to set a composite index on our timestamp.

Go to 'indexes' in Cloud Firestore and add a composite index for 'uid' and 'timestamp'.  We'll use this across collections, so give our collection id 'conditions'.  The error when we ask for this in our javascript code actually generates a link in the error.message that will create this composite index automatically for us, which we can just copy.  This is the preferred method to get things right.

Now we can query:

    conditionsCollection
    .where("uid","==", user.uid)
    .orderBy("timestamp")
    .get()
    .then(querySnapshot => {

we can also limit our responses with .limit(num), we should be able to do a 'where' on timestamp before the orderBy statement as well.

Add a Chart

First we'll install some charting libraries:

npm install --save react-native-chart-kit react-native-svg
cd ios && pod install
cd ..
npx react-native run-ios

Now we'll edit our main App to be as follows:

/**
 * Sample React Native App
 * https://github.com/facebook/react-native
 *
 * @format
 * @flow strict-local
 */

import React, {useState, useEffect} from 'react';
import {
  SafeAreaView,
  StyleSheet,
  ScrollView,
  View,
  Text,
  StatusBar,
  Button,
} from 'react-native';

import {LineChart} from "react-native-chart-kit";
import { Dimensions } from 'react-native';

import {
  Header,
  LearnMoreLinks,
  Colors,
  DebugInstructions,
  ReloadInstructions,
} from 'react-native/Libraries/NewAppScreen';

import auth from '@react-native-firebase/auth';
import firestore from '@react-native-firebase/firestore';

auth()
  .signInAnonymously()
  .then(() => {
    console.log('User signed in anonymously');
  })
  .catch(error => {
    if (error.code === 'auth/operation-not-allowed') {
      console.log('Enable anonymous in your firebase console.');
    }

    console.error(error);
  });

const conditionsCollection = firestore().collection('conditions');
const eventsCollection = firestore().collection('events');


function App() {
  // Set an initializing state whilst Firebase connects
  const [initializing, setInitializing] = useState(true);
  const [user, setUser] = useState();
  const [conditionsArray, setConditionsArray] = useState([]);
  const [eventsArray, setEventsArray] = useState([]);

  // Handle user state changes
  function onAuthStateChanged(user) {
    setUser(user);

    conditionsCollection.where("uid","==", user.uid).orderBy("timestamp").get().then(querySnapshot => {
      let cArray = [];
      querySnapshot.forEach(doc => {
        cArray.push(doc.data());
      });

      setConditionsArray(cArray);

      cArray.forEach(el => {console.log(el);});

      eventsCollection.where("uid","==", user.uid).get().then(querySnapshot => {
        let eArray = [];
        querySnapshot.forEach(doc => {
                eArray.push(doc.data());
        });

        setEventsArray(eArray);

        if (initializing) setInitializing(false);

    }, error => {console.log(error.code + ": " + error.message);});


    }, error => {console.log(error.code + ": " + error.message);});
  }


  async function addEvent(timestamp, type, data){
    console.log('sending event for user ' + user.uid);

    let eventdoc = {
        uid: user.uid,
        timestamp: timestamp,
        type: type,
        data: data
    };

    setEventsArray([...eventsArray, eventdoc]);
    await eventsCollection.add(eventdoc);

  }

  async function addCondition(timestamp, temp, humd, lux, wlux){
    console.log('sending condition for user ' + user.uid);

    let conditiondoc = {
        uid: user.uid,
        timestamp: timestamp,
        temperature: temp,
        humidity: humd,
        lux: lux,
        whitelux: wlux
    };

    setConditionsArray([...conditionsArray, conditiondoc]);
    await conditionsCollection.add(conditiondoc);
  }

  function addRandomEvent(){
    let ts = firestore.Timestamp.fromDate(new Date());
    addEvent(ts, 'TX_EXAMPLE_TYPE', 2);
  }

  function addRandomCondition(){
    let ts = firestore.Timestamp.fromDate(new Date());
    addCondition(ts, Math.random(), Math.random(), Math.random(), Math.random());
  }

  async function getAllConditions(){
    return await conditionsCollection.get();
  }

  async function getAllEvents(){
    return await eventsCollection.get();
  }

  useEffect(() => {
    const subscriber = auth().onAuthStateChanged(onAuthStateChanged);
    return subscriber; // unsubscribe on unmount
  }, []);


 const conditionItems = conditionsArray.map((conditions) =>
       <Text key={conditions.timestamp + conditions.uid + conditions.temperature}>
        {conditions.timestamp.toString()} {"\n"} {conditions.temperature} {"\n\n"}
       </Text>  );

  return (
      <>
      <StatusBar barStyle="dark-content" />
      <SafeAreaView>
        <ScrollView
          contentInsetAdjustmentBehavior="automatic"
          style={styles.scrollView}>
          <Header />
          <View style={styles.body}>
            <View style={styles.sectionContainer}>

            {user ?
                <Text>Welcome {user.uid}</Text> :
                <Text>User not logged in</Text>
            }
            {initializing ?
                <Text>initializing</Text> :
                <Text>initialized</Text>
            }

        <Button
        title="Send Random Condition"
        color="#010101"
        onPress={addRandomCondition.bind(this)}
        />

        {conditionsArray.length?
        <LineChart data={{
                labels: ['   ' + new Date(conditionsArray[0]['timestamp'].toDate()).toLocaleString()]
                        .concat(Array(2).fill("")
                        .concat([new Date(conditionsArray[conditionsArray.length-1]['timestamp'].toDate()).toLocaleString()])),
                datasets: [
                    {
                    data: conditionsArray.map(el => {return el['temperature'];}), //[20, 45, 28, 80, 99, 43],
                    color: (opacity = 1) => `rgba(134, 65, 244, ${opacity})`, // optional
                    strokeWidth: 2
                    }
                ],
                legend: ["Temperature"]
            }}
            width={0.85*Dimensions.get('window').width}
            height={180}
            chartConfig={chartConfig}
            bezier
        />
        :<Text> no data yet </Text>}

        {conditionItems}

        </View>
        </View>
      </ScrollView>
      </SafeAreaView>
      </>
  );
}

const styles = StyleSheet.create({
  scrollView: {
    backgroundColor: Colors.lighter,
  },
  engine: {
    position: 'absolute',
    right: 0,
  },
  body: {
    backgroundColor: Colors.white,
  },
  sectionContainer: {
    marginTop: 32,
    paddingHorizontal: 24,
  },
  sectionTitle: {
    fontSize: 24,
    fontWeight: '600',
    color: Colors.black,
  },
  sectionDescription: {
    marginTop: 8,
    fontSize: 18,
    fontWeight: '400',
    color: Colors.dark,
  },
  highlight: {
    fontWeight: '700',
  },
  footer: {
    color: Colors.dark,
    fontSize: 12,
    fontWeight: '600',
    padding: 4,
    paddingRight: 12,
    textAlign: 'right',
  },
});

const chartConfig = {
    backgroundColor: '#ffffff',
    backgroundGradientFrom: '#ffffff',
    backgroundGradientTo: '#ffffff',
    labelColor: (opacity = 1) => `rgba(0, 0, 0, ${opacity})`,
    color: (opacity = 1) => `rgba(0, 0, 0, ${opacity})`
};

export default App;

Notice that we're now using timestamp objects from the firestore library instead of normal javascript datatime objects.  These can easily be moved between– check the documentation.  Our queries are now ordered by timestamp.

We should see the following app, with all the data also appearing in our firebase console.  Clicking the 'Send Random Condition' will update our list, our chart, our displayed axis timestamp, and send the data to firebase:

For the code to this example, see the repo here: https://github.com/dramsay9/ReactNativeFirebaseTest.  Feel free to reuse!

Running an Example on the STM32WB Nucleo Board

STM32WBCubeIDE and STM32CubeProgrammer are the required/useful software from STM's website. This section falls into four parts: (1) set up the toolchain so you can talk to to the nucleo board, (2) flash the Bluetooth firmware, (3) ensure we can run a BLE pre-compiled example, and (4) import an STM32 example into CubeMX and run a BLE example.  

Toolchain Setup

Step 1 is to download STM32CubeIDE and STM32CubeProgrammer – I had previously had a lot of issues running this natively on Mac, but it seems like version 1.3.0 works great natively (Windows support has always been good).  To set up CubeProgrammer, you may have to download the Java JDK (one with JavaFX, aka version 8– if you've installed a more recent one [ java -version in terminal to check] you can simply delete the folder from /Library/Java/JavaVirtualmachines).  This can be installed with brew on Mac OSX:

#if you don't have brew, get it with this command
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew update

brew tap AdoptOpenJDK/openjdk
brew cask install adoptopenjdk8

You also may actually have to show the Package Contents and click on the setup executable manually.  You'll also need the ST-Link driver, installed with homebrew: brew install stlink.

The Cube Programmer interface is a new tool, and it's actually incredibly useful for checking/setting fuses, downloading firmware and programs, and reading/writing memory.  It also works over the ST-Link, SWD, and DFU interfaces, so it's a great one-stop-shop for interfacing with the STM32.

The easiest first step is to connect your USB to the STM32 Nucleo board ST_LINK port (closer to the side/header).  Of course, the Nucleo board has 2 STM32s on it– the main WB chip we'll be talking about the rest of the time, and a secondary STM32 chip that serves as an ST-LINK device for programming the WB.  The programmer chip firmware should be updated first.  

When you connect the STM32, you should see some flashing LEDs and a new device should appear in your Finder/File Explorer window.  If we open the STM32 CubeProgrammer, we should see a Serial number if we refresh the right sidebar with 'ST-LINK' selected at the very top.  Let's click Firmware Upgrade (again on the right) to update the included programmer on the Nucleo Board.

You'll have to click 'Open in Update Mode' and the 'Upgrade' to actually update the programmer.

Flashing the Wireless Co-processor Firmware

This is a two step process– we need to upgrade the underlying firmware on the coprocessor first and then flash the wireless stack we want to use (BLE in this case).

First, we should download the firmware pack from github.  Within it we find the binaries for the wireless co-process in:

STM32CubeWB/Projects/STM32WB_Copro_Wireless_Binaries/STM32WB5x

You'll also find Release Notes.html in that folder, which gives us the memory addresses we need to use for each binary in a table towards the bottom called Firmware Upgrade Services Binary Table for our first step and Wireless Coprocessor Binary Table for our second step.  We can see from this table that for the Nucleo, which is designed around the STM32WB55RG, the FUS firmware belongs at location 0x080EC000 and the stm32wb5x_BLE_Stack_full_fw should be flashed to 0x080CB000.

Option 1 (preferred): Use ST-Link

On the Nucleo board, you should be able to flash the firmware using the ST-Link. Given the same setup in STM32CubeProgrammer as above, you should be able to connect to the board simply by clicking the big green 'Connect' button.  Make sure it's in Normal/Software Reset mode– you may need to hold down the Reset button on the board, hit Connect in the software, and immediately release the Reset button to get it to work.

Option 2: Use DFU mode

If the above is giving you any trouble, we can also program the board in DFU mode.  We have to set up the jumpers on board to enable DFU mode by moving JP1 to USB_MCU and connecting pins 5 and 7 on CN7 (as shown here).  We need to make sure we have the proper DFU drivers installed; on OSX, brew install dfu-util should do it; on Windows, the DFU drivers should be installed in C:\Program Files (x86)\STMicroelectronics\STM32Cube\STM32CubeProgrammer\Drivers\DFU_Driver, where you can click on STM32Bootloader.bat.  It's also possible to get Windows DFU drivers from STM directly.  Now If you plug it in to your computer from the USB_USER port, it should appear as a DFU device on your system and be accessible under the USB tab within CubeProgrammer.  On Windows, the final thing worth considering if none of this is working is zadig libusbK conversion of existing drivers.

This has worked for me with Windows– I haven't tested in on OSX yet.  People report (including myself) difficulty re-connecting over DFU once a firmware is flashed, so hopefully option 1 is working for you.  If you really need DFU, some people have reported success by wiping the memory using the ST-Link and CubeProgrammer (use the Erasing and Programming screen and click Erase Selected Sectors after selecting all).  You could also toggle the RDP bit under "OB" option bites (to 0xBB and then 0xAA), which will clear some bits of memory (make sure PCROP_RDP is checked under PCROP Options).

For custom boards, to get into DFU mode simply requires BOOT0 gets pulled to VDD(3.3), and the USB socket to connect GND to GND, D- to PA11, and D+ to PA12.

Now that we are ideally connected to the chip using CubeProgrammer (either over the ST-Link or over DFU), we can go ahead and flash the firmware.  

We're first going to delete the existing firmware.  As of this post, there are three firmware versions (0.5.3, 1.0.2, and 1.1.0) and they must be upgraded in order (you can't jump to 1.1.0 from 0.5.3 without install 1.0.2)– our next step will be to upgrade firmware versions in order.  Finally, we'll flash the BLE firmware.

We can get to the Firmware Upgrade Service (FUS) by clicking the wifi-looking icon on the left menu; first click 'delete firmware'.  After that operation completes, we'll flash FW 1.0.2 to address 0x080EC000:

You'll probably see a lot of FUS_STATE_IMG_NOT_AUTHENTIC warnings– I certainly have while going through these processes.  This could mean you're trying to upgrade the firmware to an image that isn't allowed from the current firmware (like 'upgrading' to the same image, or skipping firmware version 1.0.2) or that something is going wrong with the upgrade process.  Try it a couple times if you get this warning; if it persists, file it away and go on to the next step.  If that fails too you can come back to this.

We can then try and upgrade again to the latest version of the firmware, at the same memory address:

Finally, we install the BLE full stack at 0x080CB000 with 'first install' checked, repeating the process above.

As a note, it is also possible to do this from the command line with the tools installed alongside CubeProgrammer.

For windows, we need to add C:\Program Files (x86)\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin to our path; the way to do this is to search for 'env' from the windows toolbar, click 'Environmental Variables', click path in the first dialog, and add the above folder.  

For OSX we can add the path of our application /Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin using a typical export command:

export PATH=$PATH:/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin

The command STM32_Programmer_CLI in OSX terminal or STM32_Programmer_CLI.exe in Windows cmd should both work; the port is specified as port=usb1 for DFU connected devices, or port=/dev/tty.usbmodem<XXXX> for OSX and port=COM<X> for Windows over ST-Link.

Some example commands that have worked for me to flash the firmware over DFU in Windows are shown here:

# first, move to the folder with the coprocessor binaries

STM32_Programmer_CLI.exe -c port=usb1 -fwdelete
STM32_Programmer_CLI.exe -c port=usb1 -r32 0x20030030 1


# IF the above says 00050300 it's at FUSv0.5.3. This MUST be first updated to v1.0.2 for any STM32WB5xx before you can update further (the latest is 1.1.0).  This is our prototype command: STM32_Programmer_CLI.exe -c port=usb1 -fwupgrade[FUS_Binary] [Install@] firstinstall=0, where Release Notes gives us Install@ parameter depending of the binary.  For STM32WB5xxG, as with Nucleo, this is:

STM32_Programmer_CLI.exe -c port=usb1 -fwupgrade stm32wb5x_FUS_fw_1_0_2.bin 0x080EC000 firstinstall=0


#now if we run the above command again we should see a new firmware version:

STM32_Programmer_CLI.exe -c port=usb1 -r32 0x20030030 1


Now I'm going to upgrade it again to the latest firmware (note difference in binary name):

STM32_Programmer_CLI.exe -c port=usb1 -fwupgrade stm32wb5x_FUS_fw.bin 0x080EC000 firstinstall=0

# This gives 'firmware not authentic error', no matter how I try to do the upgrade.  We're fine with just 1.0.2 though, so we'll ignore this issue.  Now we'll update the actual binary with the full BLE stack:

STM32_Programmer_CLI.exe -c port=usb1 -fwupgrade stm32wb5x_BLE_Stack_full_fw.bin 0x080CB000 firstinstall=0

NOTE: If your Nucleo board is giving you a 'no device found on target' error, make sure it is in 'Normal'/'Software Reset' mode, HOLD DOWN the reset button, initiate the programming, and THEN release the reset button once the ST-Link connection is 'WAITING FOR DEBUGGER CONNECTION'.

Download and Run a Pre-compiled Example

To make sure the BLE example is working properly out of the box, it's best to use the BLE_HeartRate binary and flash it directly to the board, and check it using the STM32 app downloaded from the iOS store.  

We can again use Cube Programmer with /Projects/P-NUCLEO-WB55.Nucleo/Applications/BLE/BLE_HeartRate/Binary/BLE_HeartRate_reference.hex from the second tab, 'Erasing and Programming'.  Simply pick the file, enter a start address of 0x08000000, and click 'Start Programming'.

Now we install the iOS App 'ST BLE Sensor App':

Download and Run an Example from CubeIDE

Now that we know we have the working BLE firmware and working code, and a way to test the STM32 example, let's try to import an example into CubeIDE where we can edit the C code and then download it to the Nucleo, and see if we get the same results.

For this example, we'll use the same BLE_HeartRate project, except now it will be the uncompiled C code we can then edit.  

Select File->Open Projects from File System, then hit the directory button and select the Projects\P-NUCLEO-WB55.Nucleo\Applications\BLE folder.  Click Deselect All, and then choose BLE\BLE_HeartRate\STM32\BLE_HeartRate, which is a System Workbench project.

If you hit 'okay' through the next few dialogs, you should have a project that will build and debug, connecting once again to the app!  Make sure that your Nucleo board connects, that you can't see the HRSTM, and that it appears once you 'continue' the debug after programming.

Honestly, the OSX version of things doesn't work easily for this, and I'm not sure why– I get hard faults when I attempt to build/debug.  Mac support has slowly been improving, but for this I'd recommend virtualizing Windows instead with CubeIDE.

There are a surprising number of ways to get hung up at this step, and imported projects aren't structured as nicely as CubeIDE-native IOC-based projects.  There also appear to be some limitations with using BLE and FreeRTOS at the same time if you stick with the standard toolchain CubeMX and CubeIDE toolchain.

Creating an Example App that Receives BLE from the STM32

React-Native makes things nice and easy to develop across platforms.  Expo is an environment that will let you write and hot-reload code from your browser and push changes to the app store; it's a really great tool.  

Unfortunately Expo doesn't support BLE.  Also unfortunately, you can't test your code in the iphone simulator included in XCode; they don't have support for interfacing with bluetooth on your Apple computer.  That means we need to do our testing live on a real iPhone, and we need a developer account to push things to a real phone.

To do this we need a developer account, XCode, react-native, and polidea's ble plx react native library.

Install the Tools

Install Xcode from the App Store (or older versions from here if the latest version isn't compatible with your OS version and you don't want to upgrade.)  

From a terminal install xcode command line tools with xcode-select --install.  You also have to accept the xcode license with sudo xcodebuild -license.  You should also set up a developer account; with Xcode open, click Xcode -> Preferences.  Go to the Accounts tab, and add your developer account (which you might have to register for if you don't have one).  Click manage certificates and add one using the add button at the bottom– this will give you a certificate for this computer.

Now we need watchman, flow, nvm, and the react native command line interface:

brew install watchman nvm flow
echo "source $(brew  --prefix nvm)/nvm.sh" >> ~/.bash_profile
source ~/.bash_profile
nvm install node && nvm alias default node
npm install -g react-native-cli

Set up the Project

#create a project
npx react-native init ReactNativeBLETest
#(install cocoapods with Homebrew if prompted)

#add the ble pod and generate
cd ReactNativeBLETest
npm install --save react-native-ble-plx
sudo xcode-select --switch /Applications/Xcode.app
cd ios && pod install

Now we can open this is Xcode– click on the .xcworkspace file to open it, NOT on the xcodeproj file (it won't build and you'll receive a cocoapod modulemap not found error otherwise)!

Open the main project folder and the Info.plist; right click in the area under the rows, click Add Row, and then scroll down to find 'Privacy– Bluetooth Always Usage Description'.  No need to fill in the description string.

Next we select the high level project (the one with the blue icon in the left project explorer) and click Signing and Capabilities.  Here we select our developer account from the dropdown menu (so we can sign it and test on our phone), and we also click the '+ Capability' button along the top, and select background modes to reveal an additional menu.  From this menu we can select 'Uses BLE accessories' as seen below:

Now we'll set our target to our actual iPhone.  Plug in the phone with a cable to the computer, and in the main Xcode menu select Product -> Destination -> iPhone (under Device).  You should also be able to select it from the top bar of Xcode.  

Make sure your iPhone is connected to the same WIFI network as your computer.  Now let's hit the play button and see if it builds and loads onto our phone!

What should happen is that a terminal opens with the React logo.  At the same time, to start debugging, you should open a Chrome/Firefox window, navigate to localhost:8081/debugger-ui/, and open the developer tools console with cmd+option+I.  After you wait a minute or two, the example app should appear on your phone.  Shake it, and hit 'Debug'.  We should be able to reload the app (again from the Shake menu) after refreshing the debugger site and see the same logging in our browser console that we see below.

Troubleshooting: if you get a modulemap error, you probably didn't open the project from the .xcworkspace file.  Do that instead.

If you get a 'Could Not Locate Device Support Files' error, you have an old iPhone like me.  You'll need to git clone https://github.com/iGhibli/iOS-DeviceSupport.git  and then enter the folder and run .sudo ./deploy.py and restart Xcode.

Add and Test BLE Functionality

We'll start by verifying we can accept data over BLE from the heart rate example we already have running on the Nucleo board.  First, double check that you can still see the nucleo board as HRSTM within the official STM32 app.

In our main, top-level project directory, we'll add a BLE.js file alongside the App.js.  Within BLE.js we'll add this basic code:

//BLE.js

import React, { Component }  from 'react';
import {
  View,
  Text,
} from 'react-native';

import { BleManager } from "react-native-ble-plx";

export default class BLE extends Component {

  constructor() {
    super()
    this.manager = new BleManager()
    this.state = {info: "", values: {}}
    this.ble_devices = {};
  }

  info(message) {
    this.setState({info: message})
  }

  error(message) {
    this.setState({info: "ERROR: " + message})
  }
  
  updateValue(key, value) {
    hexval = this.base64ToHex(value);
    console.log('update ' + key + ' : ' + hexval)
    this.setState({values: {...this.state.values, [key]: hexval}})
  }

  base64ToHex(str) {
    const raw = atob(str);
    let result = '';
    for (let i = 0; i < raw.length; i++) {
        const hex = raw.charCodeAt(i).toString(16);
        result += (hex.length === 2 ? hex : '0' + hex);
    }
    return result.toUpperCase();
  }

  componentDidMount() {
    if (Platform.OS === 'ios') {
      this.manager.onStateChange((state) => {
        if (state === 'PoweredOn') this.scanAndConnect()
      })
    } else {
      this.scanAndConnect()
    }
  }

  scanAndConnect() {
    this.manager.startDeviceScan(null,
                                 null, (error, device) => {
      this.info("Scanning...")
      console.log(device)

      if (error) {
        this.error(error.message)
        return
      }

      this.ble_devices[device.id] = {
            'name': device.name,
            'rssi': device.rssi
      }

      if (device.name === 'HRSTM') {
        this.info("connecting to HRSTM")
        this.manager.stopDeviceScan()
        device.connect()
          .then((device) => {
            this.info("Discovering services and characteristics")
            let r = device.discoverAllServicesAndCharacteristics()
            console.log(r)
            return r
          })
          .then((device) => {
            console.log('services')
            device.services()
              .then((services) => {
                  console.log(services)
                  console.log('characteristics')
                  for (s in services){
                      console.log(services[s])
              device.characteristicsForService(services[s].uuid).then((c)=> {
                          for (i in c){
                              console.log(c[i])
                              if (c[i].isNotifiable){
                                  console.log('registering notifiable!!')
             device.monitorCharacteristicForService(c[i].serviceUUID, c[i].uuid, (error, characteristic) => {
                                      if (error) {
                                        this.error(error.message)
                                        return
                                      }
                                      this.updateValue(characteristic.uuid, characteristic.value)
                                  });
                              }
                          }
                      })
                }
            })
          })
          .then(() => {
              this.info("Listening")
          }, (error) => {
              this.error(error.message)
              this.info(error.message)
          })
      }
    })
  }

  render() {
    return (
      <View>
        <Text>{this.state.info}</Text>
        {Object.keys(this.ble_devices).map((key) => {
            return <View key={key}>
                <Text style={{fontWeight:'bold',color:'red'}}>
                    {this.ble_devices[key]['name'] + ' : ' + this.ble_devices[key]['rssi']}
                </Text>
                <Text key={key}>
                {key}
                </Text>
                </View>
        })}

        {Object.keys(this.state.values).map((key) => {
          return <Text key={key}>
                   {"\n" + key + ": " + (this.state.values[key])}
                 </Text>
        })}
      </View>
    )
  }
};

After creating this component, we can integrate them into the 'getting started' app by editing the App.js file in the top level directory.  We first add a reference to our BLE component at the top of the file:  import BLE from './BLE';.  Secondly we add the BLE component to our main view in App.js– in the line just below the <Header /> we add <BLE />.  

Now we'll go back to our app, shake, and click reload (or go to our react terminal and hit 'r').  And voila!  BLE devices are scanned, HRSTM is connected to, its services and characteristics are enumerated, and it registers a streaming service to write data to the screen.

Digging Into Bluetooth

Let's review Bluetooth, and how the communication works on the STM32WB.

How Bluetooth Works

Bluetooth devices have a MAC address or similar, certified 12-digit hex address (commonly BD_ADDR).  To talk over bluetooth, we have a discovery process, a negotiation, and then a connection in active (ongoing), sniff (interval), hold (predefined sleep), or park (sleep until master commands wake) modes.  If devices are paired once, they will then be bonded and automatically establish a connection.  The pairing process varies; it can just work, require PINs, codes etc.

Bluetooth works with one master and (potentially many) slaves.

Bluetooth devices implement different profiles.  HID (human interface device) is a common one for input devices; SPP (Serial Port Profile) is good for replacing serial comms (data bursts), and there are others for audio (A2DP, APTX).  

Bluetooth classes refer to range; 1=100m, 2=20m, and 3=5m.

We have Bluetooth 2.1 and 3, where the max basic speed is ~2.1Mbps (though 3 introduced a high speed mode capable of 24Mbps).  Bluetooth 4 introduces the categories of Classic, High Speed (HS), and Low Energy or Smart (BLE).  From now on I'll call Bluetooth Classic 'Bluetooth', as it really matches the previous 2.1/3 specs.  HS is once again 24Mbps (This is actually more like WIFI on the physical layer– normally we think of bluetooth as a quickly changing frequency hopping carrier in the 2.4GHz band, but the 24Mbps uses a standard wide-band frequency division technique).

GAP

GAP (Generic Access Profile) is how a Bluetooth device advertises and connects.  GAP defines the role for a device as central or peripheral, and controls the advertising data and scan response packets.  Advertising packets are mandatory and sent out at intervals; scan responses are optional to provide a bit more information to scanning devices in the discovery phase.  Both packets contain up to 31 bytes of data.  Advertising intervals are on the order of tens of ms to seconds.

This advertising process is usually meant to establish connections, but it can be hijacked to simply advertise data to anyone around in the 31 byte payload– this is called Broadcasting in BLE.  Advertising packets are structured as:

Preamble | Access Address | PDU | CRC | CTE

The preamble is 1 byte of alternating 0s and 1s, for synchronization.

The access address is a 6 byte value that is unique to that type ofadvertisement. For BLE, that address is always 0x8E89BED6.

the CRC is a 3 byte cyclic redundancy check (error detection), and the CTE is a small 16-160 us burst of a '1' value known as a continuous tone extension, sent 250 kHz above the main carrier frequency, to measure transmission path (IQ) quality.

The PDU, or protocol data packet is 2-258 bytes, and is broken down as follows:

Header | Payload

Where the Header is 16 bits that break down into:

PDU Type | RFU | ChSel | RFU | ChSel | Length |

PDU type is a 4 bit number, most frequently ADV_IND, or 0b0000.  This type describes a connectable device that is advertising itself to any available central.

RFU is 1 byte reserved for future use; ChSel is a byte that represents some information about Tx and Rx channels depending on the PDU Type.

Length is an 8 bit number that tells the number of bytes in the payload.

For ADV_IND Advertising PDU types, the Payload looks like:

AdvA | AdvData

Where AdvA is the device's own 6 byte BD_ADDR (or MAC address), and AdvData is a 0-31 byte that of repeating units that follow the structure:

AD Length | AD Type | AD Data

Where AD Length is 1 byte and defines the length of AD Data in bytes (up to 29); and AD Type is a 1 byte value defined by the spec.  The payload typically includes a Device Name that is user friendly (AD Type=0x09, up to 248 bytes in UTF-8) and the Service UUIDs of services advertised on this device (AD Type=0x07).  

Because the payload may not be long enough to include everything we need (a single UUID will take 16 of the 31 possible bytes in the AdvData section of the packet), we might require the Scan Response feature to send multiple packets in a row with all of the data we care to share.

GATT

GATT (Generic Attribute Profile) is the abstract, general implementation of a BLE profiles.  Specific profiles like the Heart Rate Profile or the Pulse Oximeter Profile simply define the behavior and communication patterns between a peripheral and a master device.

Any GATT or GATT-style profile structures data using the Attribute Protocol – a lookup table with four columns:

1. a 16-bit index known as the handle (0x0001- 0xFFFF), which is guaranteed not to change for a given GATT Server.
2. a universally unique identifier, or UUID, which describes the attribute type, which is a 128-bit number, but if it is one of the predefined ones coming from the bluetooth spec it can be described in 16-bits (i.e. 0x180F  (battery service), which are 'inserted' into the standard bluetooth base 128-bit frame.  For the ones we'll use, we'll only need the 16 bit version.  For non-custom UUIDs, this will always look like 0000xxxx-0000-1000-8000-00805F9B34FB, with the x's replaced by the UUID of the attribute of interest,
3. a  value, which is variable in length and format depending on the UUID that maxes out at 512 bytes.  This value can be indexed and contain multiple pieces of arbitrarily composed data, and
4. a set of permissions for access type, encryption, and authorization  

The Attribute Protocol defines the peripheral as a GATT Server; the master is the GATT Client.  Typically, a peripheral will suggest an interval at which it would like to be polled; however it's up to the master how frequently these requests are actually initiated.  These Client initated commands can be a Read, a Write without Notification, or a Write.  The Client may also put the Server in Notification mode (the peripheral will push data to the Client and expect an acknowledgement) or in Indication mode (the peripheral will push data and expect no acknowledgement).    In all cases, the Client controls and initiates communication.

For BLE devices, the Profile is a collection of Services that each contain Characteristics, some of which contain Descriptors.  We can use the general GATT profile, or other official GATT-based profiles like the HR profile, which follows the same rules and structure (but invokes specific services).  All services, characteristics, and descriptors have a UUID that defines their type.

For services and characteristics, it's typical to have an initial attribute declaration that is read-only and describes the layout of the data.  There is a UUID for 'SERVICE_DECLARATION' (0x2800) that starts every service; it simply contains the service UUID of the service that is about to follow.  The Service UUID does not show up in the UUID field; it's just a value in for the service declaration UUID.

The 'CHARACTERISTIC_DECLARATION' (UUID=0x2803) which is at the beginning of every characteristic defines the properties (Write/Read/Notify etc), the handle (the address in the look up table), and the UUID for a characteristic.  Obviously, in this case, the characteristic UUID does appear in the UUID field of the attribute located at that handle, along with the actual data.

After the characteristic, a descriptor, service, or characteristic declaration must follow.  Descriptor UUIDs specify the data it contains, so it simply contains metadata related to the preceding characteristic.  It does not point to another entry.  The R/W Client Characteristic Configuration Descriptor (CCCD), for instance, is required for any characteristic that can Notify or Indicate (pro-actively push data to the main device), as this behavior must be turned on and off by the Client.  The other properties (Broadcast, Read, Write without response, Write) are indicated in the Characteristic declaration and don't require a descriptor.

As a quick grounding example, the HR Profile defines the 'sensor' as a Server composed of the HR Service and the Device Information Service, both mandatory. It also specifies a client that must support collecting data from the HR service, but optionally implements the Device Information Service.  It describes optimal settings for advertising and connection of unbonded and bonded devices.

the HR Service is composed of mandatory HR Measurement Characteristic and HR Measurement CCCD, where the HR Measurment can Notify and the Configuration is R/W.  It has an optional readable Body Sensor Location Characteristic and a writable HR Control Point characteristic.

The HR Measurement Characteristic contains within its value: (1) a Flags Field [that includes value format UINT8/UINT16, skin contact status DETECTED/UNDETECTED, energy expenditure INCLUDED/UNINCLUDED (relies on HR Control Point), RR-interval INCLUDED/UNINCLUDED], (2) a HR Measurement value Field (UNIT8/16 depending on flag), (3) an Energy Expended Field (UINT16), and (4) an RR-interval field.

The HR Measurement CCCD is a simple flag that allows the Client to control whether the Service is actively notifying it (pushing data) or is turned off.

This Service in the ATT structure would look like a table composed of the following rows (ignoring the handle indices and the permissions):

• UUID=SERV_DELARE_UUID, val=HR_SERVICE_UUID
• UUID=CHAR_DECLARE_UUID, val= HR_CHAR_UUID/props/handle
• UUID=HR_CHAR_UUID, val=HR data
• UUID=CCCD_UUID, val=Notify on/off

Any service with one mandatory notification characteristic will have the same structure, and the exact same UUID values for rows 1,2, and 4.

The Basics of BLE on the STM32WB

Background

As we know and have seen, the STM32WB has a separate co-processor to handle wireless communication, and we flash a binary to it that completely hides and abstracts everything that is happening on board.  To issue commands and set up our BLE peripheral, we have to use the Inter Processor Communication Controller (IPCC) or 'Mailbox'.  Let's dig into what's going on; AN5289 and AN5270 are good references for this.  (A note, they use the term 'IP' in some of these documents to refer to peripherals or other functional units on board the chip; this comes from the use of 'intellectual property' in the semiconductor industry covering reusable soft and hard logicical 'cores' that do some sort of processing, and make up the complete chip design.)

CPU2 runs the BLE firmware and controls the physical and link layer (up to and including GAP/GATT); CPU1 needs a BLE host stack alongside our application. Shared peripherals between the two are protected by semaphores– these include Sem0 for the RNG (Random Number Generator, it is recommended to generate a startup pool of these), Sem1 for the PKA (Public Key Algorithm), Sem2/6/7 for FLASH protection, Sem3/4/5 for the RCC (Reset and Clock Control, which also matters for power states).

CPU2 executes registers in the 'sequencer', up to 32 functions (and execution can be interrupted), and when no functions are present it goes into a low power state.  To use it, we have to do a few things:

//set max # supported functions
UTIL_SEQ_CONF_TASK_NBR = 32 

//register a func to be used by the sequencer
UTIL_SEQ_RegTask()

//start the sequencer in the background
UTIL_SEQ_Run()

//call the function when we need to execute it
UTIL_SEQ_SetTask()

There are other useful UTIL_SEQ functions for making the sequencer idle, pausing/resuming tasks, and managing events (the sequencer can be told to wait for an 'event', and then resume operation when that event is set or EvtIdle is called.  You can also check if an event is pending, and replace an existing WaitEvt event with a new one.)

All of these functions are defined in Utilities/stm32_seq.c.  

CPU2 uses a 'timer server' composed of virtual timers based on the Real Time Clock (RTC) wakeup timer.  After the initiation of the server with  HW_TS_Init, functions that create, start, stop, delete, etc virtual timers all follow the pattern HW_TS_Command().  

All of these functions are define in User/Core/hwtimerserver.c.

CPU2 uses a 'low power sequencer' that can recieve input from 32 users and computes the lowest power state, and gives hooks for entering/exiting low power modes.  To use it, we create an ID UTIL_LPM_bm_t ID and set the low power mode for either 'off' and 'stopped' condition using UTIL_LPM_SetOffMode(ID, state), and then call UTIL_LPM_EnterLowPower() .  Callbacks are called when entering/exiting these modes, of the form UTIL_LMP_ExitOffMode.

All of these functions are defined in Utilities/stm32_lpm.c.

It's worth poking through the headers for Middlewares/STM32_WPAN/ble_xxx just to see how those map to our previous understanding of GAP, GATT, and the underlying host controller abstractions.

Digging into the STM32WB BLE Code

So, given our understanding of GAP, GATT, services, and BLE above, the rough structure we care about is:

(1) we define a Service in User/STM32_WPAN/App with a suffix _app.c, who only publicly expose a void ServiceAPP_Init() function.  This function defines behavior; for the HRService, it uses timers from the timer server to call the sequencer SetTask at each interval defined in the HRContext to run the measurement task it registers with UTIL_SEQ_RegTask.  This registered function takes a measurement and updates the value for a characteristic using (ultimately) aci_gatt_update_char_value, which (if we look at ble_gatt_aci.h) automatically will send data for notifications/indications that are enabled.

(2) These service Init() functions are called from APP_BLE_Init() in User/STM32_WPAN/app_ble.c.

(3) In main, our interface to the BLE peripheral is managed with APPE_Init() in tandem with the sequencer, which runs with a default parameters that force it to consider all registered tasks.  APPE_Init() is declared in User/Core/app_entry.c, where it initializes the timer server and power modes.

After initialization of the transport layer is called in APPE_Init(), we see:

/**
* From now, the code is waiting for the ready event ( VS_HCI_C2_Ready )
* received on the system channel before starting the Stack
* This system event is received with APPE_SysUserEvtRx()
*/

APP_BLE_Init() from (2) above is called from APPE_SysUserEvtRx() in app_entry.c;  APPE_SysUserEvtRx() is called when CPU2 sends a ready signal that comes from this APPE_Init() process initializing CPU2 in app_entry.c.

It's worth noting that the user section of APPE_Init() also calls APPD_Init() in app_debug.c, which sets up either HAL managed debugging or exposes debugging traces on the GPIO pins.

Below is the structure as elaborated in the Application Note AN5289.  The structure is not the simplest, so it's worth spending a little time poking around and getting familiar:

The Example Services

DTM is a Direct Test Mode example in line with bluetooth spec– it ignores CPU1 and simply passes through UART commands from the UART peripheral.  This is great for hooking it up to the computer and making sure the RF circuitry works, but it's not great for us since it doesn't expose an interface for applications running on CPU1.

The HR example is nice because it notifies the master, but it is quite complex as we've seen, and it's intended for HR data.  This could be adapted for a service that requires the notifiction structure with a fair amount of work.  It implements the Bluetooth Spec defined HR Service.

STM offers two proprietary services: the P2P Service and the FUOTA Service (Flash Update Over-The-Air).  The example we will actually use for everything we're going to do is the P2P service, which features two way communication between devices or a device and a smartphone application.  One characteristic of the service features a R/W value (polled and set by the central to interact with the LED); the other is a notification characteristic (pushed by the peripheral to the device asynchronously when a button is pressed on the peripheral).

The P2P example advertises itself over GAP using a manufacturer specific packet.  This is still using the ADV_IND packet as described in the GAP section above, but in addition to using industry standard AD_Types like Service UUID or Local Name, it appends a Manufacturer specific AD_Type (=0xFF):

It is possible to set the device up as a router or in FUOTA mode, but we will care only about setting it up as a P2P server.  For this, we expect values of DevID = 0x83 (CFG_DEV_ID_P2P_SERVER1).  Group B Features are mostly reserved for future use (RFU) with the exception of turning on OTA reboot requess and Thread support, which we'll leave off (Group A and B should just be set to all zeros).   The last six bytes are the optional BD_ADDR, which is redundant in the payload.

We create the packet payload by adding AdData (the section of repeating [Length | AD Type | AD Data]) using aci_gap_set_discoverable() for both the manufacturer specific data and a local_name, to identify our application.

For full details, I encourage you to read through the AN5289 manual pages 67-77 (Section 7.4).

Moving Towards Our Own Application

Let's start by loading in and testing the BLE_p2pServer example application, the same way we did the HR example.  Import it into CubeMX, load/run it through the debugger onto our Nucleo board, and open the STM BLE example application to connect.  You'll see that we can control the LED from the app; we can recieve a timestamped alarm when the button is pressed; we can also turn on cloud logging where we control the logging interval!  This is a pretty nice general purpose example.  Hopefully this should only take you a minute or two to get running at this point; if not, it's better to work out the kinks in your toolchain first.

Our Goals

Now we're going to use this P2P Server as a starting point for our own custom code.  We'll make the following changes, familiarizing ourselves with the code in the process:

• 1. Change the human readable name of the device that is advertised
• 2. Use our React app to get notifications from the button
• 3. Use our React app to turn the LED on and off and query its state
• 4. Send a larger packet than a 0x00/0x01 from the peripheral to the central (a timestamp using the RTC, for instance)
• 5. Send a larger packet than a 0x00/0x01 from the central to the peripheral (a timestamp, for instance)
• 6. Log the incoming peripheral data and make sure it logs with the app in the background
• 7. Edit the Peripheral to store data that isn't recieved/when notifications are off and retransmit it when the Central bonds again

Change the Advertising Name

First let's edit the human readable BLE advertised name.  We go to STM32_WPAN/App/app_ble.c, and in line 240 we see the start of the advertising data construction.

#if (P2P_SERVER1 != 0)
static const char local_name[] = { AD_TYPE_COMPLETE_LOCAL_NAME ,'P','2','P','S','R','V','1'};
uint8_t manuf_data[14] = {
    sizeof(manuf_data)-1, AD_TYPE_MANUFACTURER_SPECIFIC_DATA, 
    0x01/*SKD version */,
    CFG_DEV_ID_P2P_SERVER1 /* STM32WB - P2P Server 1*/,
    0x00 /* GROUP A Feature  */, 
    0x00 /* GROUP A Feature */,
    0x00 /* GROUP B Feature */,
    0x00 /* GROUP B Feature */,
    0x00, /* BLE MAC start -MSB */
    0x00,
    0x00,
    0x00,
    0x00,
    0x00, /* BLE MAC stop */
};
#endif

This is true for the various enumerated P2P_SERVERs on the following lines as well.  We can change the local name in this static const char local_name.

We also can change it in line 863:

if (role > 0)
  {
    const char *name = "P2PSRV1";
   ...

The first instance of these is the 'local_name'; the second instance is the 'name'.  These are advertised as two separate fields, but it's best practice for our applications just to make them the same thing.  

A word of caution: I thought this hadn't worked when I updated it, for a while.  You might need to restart/repower the Nucleo AND whatever device you're using to look at BLE; these names can be cached opaquely at a low level.  They really aren't supposed to change.  If they don't update, reset everything, turn on/off bluetooth, move on, and come back to it later.

Read and Write the Button State in React

We can use the exact same code as for the HR example here, changing the name of the device we want to connect to in the scanAndConnect function (to whatever we set it to above).  It will connect and register for the notifications of the button pressing!  We can add a little code that will print things conditionally on the button press in our BLE render function, like so:

{this.state.values['0000fe42-8e22-4541-9d4c-21edae82ed19']=='0101'
            ?
            <Text> Button Pushed
            </Text>
            :
            <Text> Button NOT Pushed
            </Text>
}

The UUID is set for this notification of the button given the spec in AN5289 (the notify characteristic).

The above code will show 'Button Pushed' or 'Button NOT Pushed' in your React app, toggled by the actual button press!

Read and Write the LED State in React

Now let's connect and control the LED.   We can also see in our debugger that we have a characterstic with UUID '0000fe41-8e22-4541-9d4c-21edae82ed19' (as expected) that has isReadable==True and isWritableWithoutResponse==True.

We can see there are three options for writing a value to a characteristic without a response (https://github.com/Polidea/react-native-ble-plx/wiki/Characteristic-Writing)– each one uses an ble object at a different level of abstraction, and requires the missing information passed (blemanager object, the device object, and the characteristic itself).  We'll just register our characteristic and use characteristic.writeWithoutResponse(valueBase64).

First we modify our constructor so our state has writeCharacteristic and ledState field:

this.state = {info: "", values: {}, writeCharacteristic: null, ledState: false}

Now we'll modify our loop that runs through the the device characteristics to append the write characteristic we expect:

if (c[i].isWritableWithoutResponse){
    console.log('saving characteristic that is writable!!')
    this.setState({writeCharacteristic: c[i]})
}

Next, we'll make a write function that toggles the LED given our LEDState (we'll also need functions to convert a common sense hex value to base64 (adapted from https://stackoverflow.com/questions/23190056/hex-to-base64-converter-for-javascript):

  
  hexToBase64(str) {
    return btoa(str.match(/\w{2}/g).map(function(a) {
        return String.fromCharCode(parseInt(a, 16));
    }).join(""));
  }

  toggleLED(){
    console.log('toggle LED function called!')
    var newLedVal = !this.state.ledState
    if  (this.state.writeCharacteristic){
        if (newLedVal){
        this.state.writeCharacteristic.writeWithoutResponse(this.hexToBase64('0101'))
        console.log('wrote ' + this.hexToBase64('0101'))
        }
        else {
        this.state.writeCharacteristic.writeWithoutResponse(this.hexToBase64('0100'))
        console.log('wrote ' + this.hexToBase64('0100'))
        }
        this.setState({ledState: newLedVal})
    }
  }

Finally we need a button to call this toggleLED function in the renderer:

<TouchableHighlight style={{borderColor: this.state.ledState ? 'green' : 'red', borderWidth: 4, borderRadius: 10, height:30, width:100, justifyContent:'center', alignItems:'center'}} onPress={this.toggleLED.bind(this)}>
     <Text>LED IS {this.state.ledState ? 'on' : 'off'}</Text>
</TouchableHighlight>

And that's all there is to it! We now have a React app with a small button that tracks the LED state and toggles it on and off.

Send More Information

We're gonna bump up our data from 8 bits; for me, the target is really timestamped 16 bit values (RTC timestamps are 64 bits, so >10 bytes).  The default configuration should work up to 20 bytes; if we need more, we need to edit the MTU size ( CFG_BLE_MAX_ATT_MTU  in app_conf and potentially renegotiate the connection using aci_gatt_exchange_config and hci_le_set_data_length), but for our purposes we'll stick within the 20 byte size.  Here we'll send 16 bytes.

First, let's take a look at the existing code for sending our current notification.  It exists across a  few different files:

 //from p2p_server_app.c
 P2PS_Send_Notification(void) {
 
   P2PS_STM_App_Update_Char(
     P2P_NOTIFY_CHAR_UUID, 
     (uint8_t *)&P2P_Server_App_Context.ButtonControl
   );
 
 }
  
//from p2p_stm.c  CALLS:
  
P2PS_STM_App_Update_Char(uint16_t UUID, uint8_t *pPayload)  {
  
  aci_gatt_update_char_value(
    aPeerToPeerContext.PeerToPeerSvcHdle,
    aPeerToPeerContext.P2PNotifyServerToClientCharHdle,
    0, /* charValOffset */
    2, /* charValueLen */
    (uint8_t *)  pPayload
  );
}
 
 //from ble_gatt_aci.c  CALLS:
 
 aci_gatt_update_char_value(uint16_t Service_Handle,
                                      uint16_t Char_Handle,
                                      uint8_t Val_Offset,
                                      uint8_t Char_Value_Length,
                                      uint8_t Char_Value[])
                                      
                                      

The last of these is updating a characteristic that is already registered with a certain packet size:

//from p2p_stm.c (that third line is the packet byte size

aci_gatt_add_char(aPeerToPeerContext.PeerToPeerSvcHdle,
                      UUID_TYPE_128, &uuid16,
                      2,
                      CHAR_PROP_NOTIFY,
                      ATTR_PERMISSION_NONE,
                      GATT_NOTIFY_ATTRIBUTE_WRITE, /* gattEvtMask */
                      10, /* encryKeySize */
                      1, /* isVariable: 1 */
                      &(aPeerToPeerContext.P2PNotifyServerToClientCharHdle));
 
 
//from ble_gatt_aci.c  CALLS:

tBleStatus aci_gatt_add_char(uint16_t Service_Handle,
                             uint8_t Char_UUID_Type,
                             Char_UUID_t *Char_UUID,
                             uint16_t Char_Value_Length,
                             uint8_t Char_Properties,
                             uint8_t Security_Permissions,
                             uint8_t GATT_Evt_Mask,
                             uint8_t Enc_Key_Size,
                             uint8_t Is_Variable,
                             uint16_t *Char_Handle)

First let's make a version of P2P_STM_App_Update_Char that accepts something other than a 2 byte char.  In p2p_stm.c:

tBleStatus P2PS_STM_App_Update_Int16(uint16_t UUID, uint16_t *pPayload, uint8_t num_words) 
{
  tBleStatus result = BLE_STATUS_INVALID_PARAMS;
  switch(UUID)
  {
    case P2P_NOTIFY_CHAR_UUID:
      
     result = aci_gatt_update_char_value(aPeerToPeerContext.PeerToPeerSvcHdle,
                             aPeerToPeerContext.P2PNotifyServerToClientCharHdle,
                              0, /* charValOffset */
                             2*num_words, /* charValueLen */
                             (uint8_t *)  pPayload);
    
      break;

    default:
      break;
  }

  return result;
}

And we need to declare our new function in the appropriate header:

//STM32CubeWB/Middlewares/ST/STM32_WPAN/ble/svc/Inc/p2p_stm.h

...
//add this line
tBleStatus P2PS_STM_App_Update_Int16(uint16_t UUID,  uint16_t *pPayload, uint8_t num_words);

And of course we need to edit the original declaration of the characteristic so it's set up to recieve 16 bytes in p2p_stm.c.  We simply have to change the Char_Value_Length from 2 to 16.

Now let's edit our button push  in P2PS_Send_Notification from p2p_server_app.c to try and send a larger packet:

...

const uint16_t test_data[8] = {0x0123, 0x4567, 0x89AB, 0xCDEF, 0x0A0A, 0x1B1B, 0x2C2C, 0x3D3D};
  
if(P2P_Server_App_Context.Notification_Status){ 
  ...
  //comment out our old command to send ButtonControl Byte
  //P2PS_STM_App_Update_Char(P2P_NOTIFY_CHAR_UUID, (uint8_t *)&P2P_Server_App_Context.ButtonControl);
  
  //call our new function
  P2PS_STM_App_Update_Int32(P2P_NOTIFY_CHAR_UUID, test_data, 8);
       
       

With the above code, we'll see in our React App that pushing the button sends all the data; however the byte order is reversed ( 0x2301, 0x6745, 0xAB89, 0xEFCD, ...).  However, if we use the same function and send an array of bytes instead of words, the correct order is preserved:

//same test data as above, but as bytes
const uint8_t test_data[16] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0x0A, 0x0A, 0x1B, 0x1B, 0x2C, 0x2C, 0x3D, 0x3D};

//cast it to (uint16_t *) so it will work with our previous function
P2PS_STM_App_Update_Int16(P2P_NOTIFY_CHAR_UUID, (uint16_t *)&test_data, 8);

We'll have to be careful when working with words on the STM32 so that the byte order is not reversed.

We also notice that we can send less data than the maximum specified packet size using this technique, without modification:

//same test data as above, but half as much
const uint8_t test_data[8] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF};

//cut the passed number of words in half, though the characteristic is the same and supports the full 16 bytes 
P2PS_STM_App_Update_Int16(P2P_NOTIFY_CHAR_UUID, (uint16_t *)&test_data, 4);

So Finally, we'll finish our edits here in a way that we can easily pass byte or word arrays:

//IN p2p_stm.c

//SET aci_gatt_add_char length to *20*; that way we can send up to 20 bytes in each message

//ADD the following two functions:

tBleStatus P2PS_STM_App_Update_Int16(uint16_t UUID, uint16_t *pPayload, uint8_t num_words)
{

  uint16_t byte_reversed[num_words];

  for (uint8_t i = 0; i < num_words; i++){
	byte_reversed[i] = (pPayload[i] & 0xFF00) >> 8 | (pPayload[i] & 0x00FF) << 8;
  }

  tBleStatus result = BLE_STATUS_INVALID_PARAMS;
  switch(UUID)
  {
    case P2P_NOTIFY_CHAR_UUID:

     result = aci_gatt_update_char_value(aPeerToPeerContext.PeerToPeerSvcHdle,
                             aPeerToPeerContext.P2PNotifyServerToClientCharHdle,
                             0, /* charValOffset */
                             2*num_words, /* charValueLen */
                             (uint8_t *)  byte_reversed);

      break;

    default:
      break;
  }

  return result;
}

tBleStatus P2PS_STM_App_Update_Int8(uint16_t UUID, uint8_t *pPayload, uint8_t num_bytes)
{
  tBleStatus result = BLE_STATUS_INVALID_PARAMS;
  switch(UUID)
  {
    case P2P_NOTIFY_CHAR_UUID:

     result = aci_gatt_update_char_value(aPeerToPeerContext.PeerToPeerSvcHdle,
                             aPeerToPeerContext.P2PNotifyServerToClientCharHdle,
                             0, /* charValOffset */
                             num_bytes, /* charValueLen */
                             (uint8_t *)  pPayload);

      break;

    default:
      break;
  }

  return result;
}


//IN p2p_stm.h

//ADD the function handles:

tBleStatus P2PS_STM_App_Update_Int16(uint16_t UUID,  uint16_t *pPayload, uint8_t num_words);
tBleStatus P2PS_STM_App_Update_Int8(uint16_t UUID, uint8_t *pPayload, uint8_t num_bytes);


//now we can call this on byte arrays and word arrays up to 20 bytes long, and the byte order will be preserved correctly when we send.

Sending more info to the STM

Within the p2p_server_app.c we find that all of the data we're sending back and forth is stored in P2P_Server_App_Context, which is a nice abstraction to help us keep data organized.

First let's add a uint64_t OTATimestamp, a uint8_t OTA12HrFormat, and a uint8_t OTADaylightSavings to the P2P_Server_App_Context struct declaration in p2p_server_app.c.  We're going to send a timestamp value over BLE from our React App.

Now we need to edit the payload handler to deal with our new timestamp value.  In the same file, we see P2PS_STM_App_Notification is the function that deals with incoming data.  We'll add one memcpy to push our timestamp value to the OTATimestamp field of the P2P_Server_App_Context struct.

#if(P2P_SERVER1 != 0)  
      if(pNotification->DataTransfered.pPayload[0] == 0x01){ /* end device 1 selected - may be necessary as LB Routeur informs all connection */
        
    	memcpy(&P2P_Server_App_Context.OTATimestamp, &(pNotification->DataTransfered.pPayload[2]), 8);
        P2P_Server_App_Context.OTA12HrFormat = pNotification->DataTransfered.pPayload[10];
    	P2P_Server_App_Context.OTADaylightSavings = pNotification->DataTransfered.pPayload[11];


    	
    	if(pNotification->DataTransfered.pPayload[1] == 0x01)
        {
          BSP_LED_On(LED_BLUE);
          APP_DBG_MSG("-- P2P APPLICATION SERVER 1 : LED1 ON\n"); 
          APP_DBG_MSG(" \n\r");
          P2P_Server_App_Context.LedControl.Led1=0x01; /* LED1 ON */
        }
        if(pNotification->DataTransfered.pPayload[1] == 0x00)
        {
          BSP_LED_Off(LED_BLUE);
          APP_DBG_MSG("-- P2P APPLICATION SERVER 1 : LED1 OFF\n"); 
          APP_DBG_MSG(" \n\r");
          P2P_Server_App_Context.LedControl.Led1=0x00; /* LED1 OFF */
        }
      }
#endif

We should alter our init code for this struct later on in the file as well to start the default values at 0x00:

void P2PS_APP_LED_BUTTON_context_Init(void){
  
  BSP_LED_Off(LED_BLUE);
  
  #if(P2P_SERVER1 != 0)
  P2P_Server_App_Context.LedControl.Device_Led_Selection=0x01; /* Device1 */
  P2P_Server_App_Context.LedControl.Led1=0x00; /* led OFF */
  P2P_Server_App_Context.OTATimestamp=0x0000000000000000;
  P2P_Server_App_Context.OTA12HrFormat=0x00;
  P2P_Server_App_Context.OTADaylightSavings=0x00;
  P2P_Server_App_Context.ButtonControl.Device_Button_Selection=0x01;/* Device1 */
  P2P_Server_App_Context.ButtonControl.ButtonStatus=0x00;
#endif

We'll also send that data back on a button press; where we had modified our P2P_Send_Notification function to send random test data, let's edit it to send the 64 bit timestamp value instead:

void P2PS_Send_Notification(void)
{
 
  if(P2P_Server_App_Context.ButtonControl.ButtonStatus == 0x00){
    P2P_Server_App_Context.ButtonControl.ButtonStatus=0x01;
  } else {
    P2P_Server_App_Context.ButtonControl.ButtonStatus=0x00;
  }
  
  if(P2P_Server_App_Context.Notification_Status){ 
    APP_DBG_MSG("-- P2P APPLICATION SERVER  : INFORM CLIENT BUTTON 1 PUSHED \n ");
    APP_DBG_MSG(" \n\r");
    
    P2PS_STM_App_Update_Int8(P2P_NOTIFY_CHAR_UUID, (uint8_t *)&P2P_Server_App_Context.OTATimestamp, 8);

    
   } else {
    APP_DBG_MSG("-- P2P APPLICATION SERVER : CAN'T INFORM CLIENT -  NOTIFICATION DISABLED\n "); 
   }

  return;
}

Just like in the case for the STM writing more than 2 bytes, we need to change the max size when we register our characteristic using aci_gatt_add_char , as well as our aci_gatt_update_char_value in p2p_stm.c (here we again make it up to 20 bytes, here we have to update it in two places):

 /**
     *  Add LED Characteristic
     */
    COPY_P2P_WRITE_CHAR_UUID(uuid16.Char_UUID_128);
    aci_gatt_add_char(aPeerToPeerContext.PeerToPeerSvcHdle,
                      UUID_TYPE_128, &uuid16,
                      20,                                   
                      CHAR_PROP_WRITE_WITHOUT_RESP|CHAR_PROP_READ,
                      ATTR_PERMISSION_NONE,
                      GATT_NOTIFY_ATTRIBUTE_WRITE, /* gattEvtMask */
                      10, /* encryKeySize */
                      1, /* isVariable */
                      &(aPeerToPeerContext.P2PWriteClientToServerCharHdle));
   
   
                      
...



tBleStatus P2PS_STM_App_Update_Char(uint16_t UUID, uint8_t *pPayload) 
{
  tBleStatus result = BLE_STATUS_INVALID_PARAMS;
  switch(UUID)
  {
    case P2P_NOTIFY_CHAR_UUID:
      
     result = aci_gatt_update_char_value(aPeerToPeerContext.PeerToPeerSvcHdle,
                             aPeerToPeerContext.P2PNotifyServerToClientCharHdle,
                              0, /* charValOffset */
                             20, /* charValueLen */
                             (uint8_t *)  pPayload);
    
      break;

    default:
      break;
  }

  return result;
}/* end P2PS_STM_Init() */

NOTE: the GATT will cache aspects of the service, including the packet size.  There is a Service Changed Characteristic for when you're doing this on the fly, but in our cases it actually probably makes sense to just be aware that updates might require a restart of various devices to populate.

EXTRA NOTE: IF YOU ARE HAVING ISSUES WITH HOT-RELOADING OF YOUR JAVASCRIPT CODE, GO TO THE NETWORK TAB IN THE BROWSER INSPECTION TOOLS AND MAKE SURE 'DISABLE CACHE' IS CHECKED!!!!

Let's grab a javascript date and put it in BCD format (in which a month like December, month 12, is coded as 0x12– we use hex bytes to represent the decimal values).  Here's some code I wrote to generate a timestamp object we can then work with on the STM32:

//at the very top of the javascript file:

Date.prototype.stdTimezoneOffset = function () {
  var jan = new Date(this.getFullYear(), 0, 1);
  var jul = new Date(this.getFullYear(), 6, 1);
  return Math.max(jan.getTimezoneOffset(), jul.getTimezoneOffset());
}

Date.prototype.isDstObserved = function () {
    return this.getTimezoneOffset() < this.stdTimezoneOffset();
}
  
  
  
//as a member function:

getDateInBCD(format12 = true) {
    //returns DAY (1byte) MONTH (1byte) DATE (1byte) YEAR (1byte) HR (1byte)
    //MIN (1byte) SEC (1byte) 12HRFORMAT (1byte, 00=24HR) AMorPM (1byte, 00=AM) 
    //DAYLIGHTSAVINGS (1byte, 00=None 01=Add1hr) 
    //all as a string

    console.log('Constructing Date...')
    //BCD means we use 0x01-0x12, skipping 0x0A-0x0F (hex *reads* right)
    var day = ("0" + new Date().getDay()).slice(-2);          //uint8_t 0x01-0x07, Mon-Sun
    var month = ("0" + (new Date().getMonth() + 1)).slice(-2);  //uint8_t 0x01-0x12
    var date = ("0" + new Date().getDate()).slice(-2);        //uint8_t 0x01-0x31
    var year = String(new Date().getFullYear()).slice(-2);    //uint8_t 0x20

    var hour = new Date().getHours();    //uint8_t Hours 0x00-0x023 if RTC_HourFormat_24, 0x00 to 0x12 if RTC_HourFormat_12
    var min  = ("0" + new Date().getMinutes()).slice(-2); //uint8_t Min 0x00 to 0x59
    var sec  = ("0" + new Date().getSeconds()).slice(-2); //uint8_t Sec 0x00 to 0x59

    //uint8_t TimeFormat to 0x00 for FORMAT12_AM, 0x40 for FORMAT12_PM
    var formatAM = hour >= 12 ? 1 : 0;
    if (format12) { hour = hour % 12; hour = hour ? hour : 12;}
    hour = ("0" + hour).slice(-2);

    //uint32_t DayLightSavings; use RTC_DAYLIGHTSAVINGS_SUB1H, RTC_DAYLIGHTSAVINGS_ADD1H, or RTC_DAYLIGHTSAVING_NONE
    var daylight = new Date().isDstObserved() ? 1 : 0; // if 1, ADD1H; else NONE

        return day + month + date + year + hour + min + sec  + '0' + formatAM  + '0' + (format12 ? 1 :0) + '0' + daylight;


  }
  
  
//now we edit our button toggle to send this info as well:
  
...
if  (this.state.writeCharacteristic){
 if (newLedVal){
  
var timestamp_string = this.getDateInBCD()
          this.state.writeCharacteristic.writeWithoutResponse(this.hexToBase64('0101' + timestamp_string))

console.log('wrote 0x0101' + timestamp_string + ' == ' + this.hexToBase64('0101' + timestamp_string))

}
...

This sends 10 bytes – the first 8 will fit into our OTAtimestamp and include DAY:MONTH:DATE:YEAR:HOUR:MIN:SEC:AMPM.  The last 2 bytes are format bytes which indicate whether it is in 24 or 12 hour format, and whether it is currently daylight savings or not and can be saved as two uint8_t vals.

All of this should give us a round trip where we can easily see our timestamp, generated from our app, sent to and stored on the STM32, and then sent back!

A Note on Endianness

Both systems are Little Endian, but BLE communication works in a Big Endian fashion.  To fix this, we need to reverse the bytes when sending/receiving, which I've chosen to do only on the javascript side of things.  I've made the following changes to ensure my packets follow the right order:

reverseBytes(str){
  //bytes are 2 chars long
  //both systems are Little Endian; transport protocol is Big Endian
  //thus, data always gets flipped in transit

 s = str.replace(/^(.(..)*)$/, "0$1"); // add a leading zero if needed
 var a = s.match(/../g);             // split number in groups of two
 a.reverse();                        // reverse the groups
 return a.join("");                 // join the groups back together
}

...

  updateValue(key, value) {
    hexval = this.reverseBytes(this.base64ToHex(value));
    console.log('update ' + key + ' : ' + hexval)
    this.setState({values: {...this.state.values, [key]: hexval}})
  }

...

var timestamp_string = this.getDateInBCD()
this.state.writeCharacteristic.writeWithoutResponse(this.hexToBase64(this.reverseBytes('0101' + timestamp_string)))
console.log('wrote 0x0101' + timestamp_string + ' == ' + this.hexToBase64('0101' + timestamp_string))

Stay tuned for more posts exploring the link between STM32 and React-Native over BLE!

See https://github.com/dramsay9/react-stm32-bluetooth-example for the working code.

Quick Reference

For react, open workspace file.  Run on phone, open http://localhost:8081/debugger-ui/.  Make sure it's connected to the same wifi as your phone.

'Device not found on target' means hold down the reset button on the nucleo, and let go after reaches 'waiting for debugger connection'.

'Could not locate device support files' means you need to download the right files from here: https://github.com/iGhibli/iOS-DeviceSupport/tree/master/DeviceSupport and then

Then, go to Applications -> Xcode. Right click and open Show Package Contents. Then, paste to Contents -> Developer -> Platforms -> iPhoneOS.platform -> DeviceSupport and restart Xcode.  (from https://stackoverflow.com/questions/39655178/xcode-could-not-locate-device-support-files)

Background capabilities requires restoreStateIdentifier and restoreStateFunction passed to BLEManager.

This blog is my attempt to reflect and capture thoughts about how and why our technology seems to be so out of sync with what is actually good for our well-being and what we need to do to realign these incentives.  I'm very interested in how attention, cognition, and behavior underlie our sense of happiness and fulfillment, and the mediating role of technology in that story.

So that explains 'tech' and 'cognition', but why 'epistemology'?  I've found that during an honest review of the psychology literature, it doesn't take long to run into serious difficulties in discerning truth.  In many ways we live in a post-truth society, and the perverse incentives of the academic world have sadly made that no less true in the softer branches of science.  

There is an ongoing replication crisis in social psychology, and the way we interact is changing at such a rapid pace that traditional research methods are being left in the dust.  A famous Nature paper showed that the best way to tell whether a study in a major psychology journal replicates is with prediction markets– in other words, our common sense is currently better at revealing psychological truths than the scientific process and peer-reviewed publication.  At the core of the replication problem is a profound crisis of statistical literacy and statistical technique.  

To say anything true about our cognition and psychology requires a deep dive into the foundations of statistics and a healthy skepticism of modern publications.  Who can we trust?  How do we evaluate them?  What are the worthwhile theories?  How can we identify quality work and reliable data without recreating the experiments ourselves?  How much should we trust our intuition, and what builds our intuition in the first place?

It goes one level further.  An epistemological shift is required to re-evaluate the scientific literature, but it's also necessary to model how we think and behave.  The top computational cognitive scientists– in designing systems that replicate human cognition most accurately– are championing stronger causal inductive biases compared to the typical statistical techniques of deep learning.  

Epistemology is explicit in cognitive science, as one of its core pursuits is to model the way we form beliefs and acquire knowledge.  Researchers in this area naturally also advocate for those principles at higher levels of abstraction.

A compelling line of argument suggests that our statistical techniques should reflect our innate epistemological processes.  We have some innate ability to discern truth and model the world, and that innate kernel can be our only arbiter of truth; in so much that modern statistical practices don't reflect that, they are failing.  

To say it another way, our minds seem to work in a Bayesian way, so we should build Bayesian models of how humans reason.  When we compare several models against each other, we should also use Bayesian techniques to reason about which one is the best.  The optimal process that captures truth in science is the one that most accurately mirrors our innate truth-seeking abilities. It's turtles all the way down.  

This is one of the most interesting and important discussions of the modern era– the bedrock of the scientific method and of model building is actively and fiercely debated.  We need to re-examine how we think about statistics and how we use its techniques to describe and predict our world.  It turns out these questions are more relevant now than ever, and we're on the brink of a major paradigm shift.

Before we can build cognition-supporting technology, we need to understand cognition.  Before we can do that, we need tools to fairly evaluate the scientific claims of social psychology and tools to model human cognition.

Ultimately, I hope that with a thorough understanding of statistics and inquiry, we can build a foundation of trustworthy scholarship that will chart the way forward.  With it, we can push the future of technology towards tools that make a real, positive impact on our behavior, attention, and feelings.