I’m an engineer and not a microscopy expert, but playing around with my (semi)built microscope, it becomes evident that light intensity plays a very important role for achieving optimal imaging conditions.
It’s become evident through experimentation that fine-tuning light intensity is essential for capturing clear and detailed images. The short video bellow is a good proof of that:
Anyway, I missed a light intensity control in my OFM, I drew inspiration from more intricate setups such as the grid illumination extension and devised a simplified version of my own. Since others may encounter similar challenges, I’m sharing my build here for anyone interested.
In order to make it work, all 4 layers of the OFM architecture must be adjusted:
GUI/API Extension:
The OFM extension, Illumination Control Extension, adds a new menu to the microscope user interface, allowing users to control light intensity via the GUI.
Driver (board library):
The pySangaboard fork has to be installed, replacing the current pySangaboard library v0.3.3. This fork introduces a new LightControl class as an optional module, exposing light control capabilities to the OFM extensions.
Firmware:
The Sangaboard fork has to be installed in the Arduino Nano (Sangaboard alternative). This forked version listens to commands from the serial port (sent by the pySangaboard library) and adjusts the duty cycle of the PWM outputs (analog outputs).
Hardware:
My OFM uses an Arduino Nano as an alternative to the Sangaboard. Two of its analog ports (PWM enabled outputs) should be connected to two LDO6AJSA modules, which serve as PWM controlled current drivers for the illumination LEDs.
Note: These forks may be merged into the main branch if deemed appropriate by maintainers. Otherwise, adjustments will be made to align the hardware with the main branch as they evolve and the required illumination control becomes native.
TLDR: I need help with the Illumination level control in OFM Connect.
I’m attempting to use the Sangaboard illumination extension to control the LED illuminator via the OFM Connect application. Just to be clear, I can move the stage in x-y and focus in Z without any issues, and am seeing excellent images.
My issue is this: I see the “sangaboard extension” options in the app, including the “Stop Stage” and “Upgrade firmware” buttons. The Stop Stage feature works as expected, as does the Upgrade firmware button. However, making changes to the CC slider under the Illumination heading on the same panel does nothing to the LED brightness. BTW, the firmware versions listed are consistent with what I believe to be running.
Using the sangaboard.py functions directly from the RPI v4 Python v3 command prompt, I am able to import the sangaboard library and issue these commands:
“from sangaboard import Sangaboard as sb”
“with Sangaboard() as sb: sb.illumination.cc_led = 0.1” Which succeeds in changing the illumination level as expected.
So my reasoning goes:
-I know the sangaboard can be told via python commands from the host RPI to make changes to the LED constant current driver. This confirms my hardware is functional and can be controlled through its fundamental library calls. I assume that because the illumination control is only available with specific sangaboard firmware, that this step confirms that I have a compatible level of firmware installed on the sangaboard.
-I see the Sangaboard Extensions in OFM Connect, including Illumination controls, which means that the OFM server has recognized that the extensions are installed so presents them to the OFM Connect Application. The firmware upgrade and stop stage features work, which confirms that the basic communication between the OFM Connect app and the sangaboard are healthy.
-So it seems like all the pieces needed to make the Illumination control are in place, but just the one feature is not working.
-The only other possible anomaly is that the PWM frequency box always shows up blank when opening the Sangaboard Extension functions window. If I make a change to the frequency, it sticks while the window is open but then is blank if I go back to “View” and reopen the Sangaboard extension again. This would suggest that the extension is not actually reading the PWM actual frequency value properly.
-One more bit of info: The behavior of the illumination controls is identical whether I run OFM Connect locally on the RPI GUI or over ethernet from my Windows 11 PC.
Any and all suggestions would be appreciated.
I have built the OFM install on RPI at least once and went through the sangaboard fork extension installation steps multiple times. I now think that I’m experiencing some anomaly other than a bad install procedure.
Thanks for your efforts on my behalf.
I am not sure @pbrugugnoli is around on the forum much. There is I think another Sangaboard extension from @filip.ayazi that also allows you to adjust the LED.
Do you see the PWM control boxes in the extension? There should be 2 pwm sliders and a cc slider, the PWM box being blank seems to indicate that the illumination module in sangaboard is not present but that is contradicted by your test in python shell.
When you tried to manually use the illumination setting via sangaboard.py, was that inside the OFM virtual environment or on the system python install? (ofm activate should put you in the OFM venv).
FYI, I’m now inclined to believe I have a software version issue.
The Openflexure Connect logs show the following error every time I launch.
(I hadn’t known there were app logs, as a complete noob in OFM)
ERROR: ‘Sangaboard’ object has no attribute ‘illumination’
Also, on the server itself, the openflexure_microscope.log contains instances showing this warning:
[WARNING] Module type “Illumination” not recognised.
I upgraded the server OFM using “sudo ofm upgrade” and tried the --pre (prelease version) but the same conditions persist.
I also did a client update with “sudo ofm update”.
Correct me if I’m wrong here…
There are four critical pieces to the sangaboard extension
base OFM server install
2)sangaboard firmware
3)sangaboard python library
4)OpenFlexure Connect app (OFM client)
The logs suggest some combination of the four are not in agreement about the “illumination” function.
What am I missing?
Filip,
I see all the expected controls under the illumination section, including the CC left/right slider, and the PWM frequency box. The slider can be operated, but just does nothing to the LED brightness level. Also, the PWM box defaults to blank, but I can use the arrows to go up or down, and can manually enter a frequency in the box, which “sticks” at least temporarily, but also does not seem to have any actual impact.
As you see in my other recent post, something in the OFM Connect application is not detecting the “Illumination” module on the server, since it throws an error in the OFM Connect client log every time I open the connection in the App, and has a similar, but slightly different wording on the server logs.
Is it possible that I’m mixing up two sangaboard extension forks? I am only aware of the Filip Ayazi one and am following the instructions on that gitlab page:
Would it make sense to start over from a fresh OFM Pi OS installation and then redo the extension? I had a 30-year career in IT managed services, so I realize that some times you just have to reformat and rebuild rather than dig into the guts for a specific root cause.
You suggestions are most appreciated.
Filip,
Thanks for your response. To answer your question about my operation of the sangaboard with python directly…
I am indeed running my manual illumination controls within the OFM virtual python environment that you get with “OFM Activate” on the RPI.
That was the only way I could even get the sangaboard library to load, since the default system python environment doesn’t appear to have the sangaboard library installed, which totally makes sense to me. I have built multiple python projects in their own virtual environments to control executable bloat when compiled to EXE’s, so I have some rudimentary understanding of virtual envs.
Also, you mention 2 PWM sliders. I have one left/right slider called CC, and one box below it called PWM Frequency. The fequency box has up and down arrows to the right end of it that successfully raise and lower the value in the box. Is that what you meant by the second slider?
I am uploading a PNG file with an image of what I see when first opening my OFM connection.
Hmm, that image shows the 2 PWM sliders are missing and there is no frequency retrieved all of which is consistent with using the unmodified version of pysangaboard. Have you followed the install steps in the sangaboard extension repository including installing the pysangaboard module from my git repo sangaboardv5 branch? It is very strange because it looks like like you do have that version when the control works in shell but the openflexure server is using the standard one without it. Did you restart the server after installing the pysangaboard version?
Filip,
I’m very grateful for your attention to my messages. It is much appreciated.
I restarted ofm multiple times, and the pi os many times as well, all with the same results.
I followed the github repo installations instructions to the letter, to the best of my knowledge, including cloning the git files and and then running the setup.py install with the develop switch.
as shown in this copy: (text between the dashed lines)
pySangaboard dependency install
To control the illumination, this extension requires a modified version of pySangaboard package, until the changes have been merged (hopefully soon) you will need to install it manually;
ofm activate
#in the ofm shell opened by above
git clone https://gitlab.com/filipayazi/pysangaboard.git
cd pysangaboard
git checkout sangaboardv5
pip uninstall sangaboard
python setup.py develop
Install
To install, clone this repo into /var/openflexure/extensions/microscope_extensions/:
cd /var/openflexure/extensions/microscope_extensions/
git clone https://gitlab.com/filipayazi/sangaboard-extension.git
If you see some permissions errors, try
sudo chmod -R g+w /var/openflexure/
sudo adduser pi openflexure-ws
Log out and back in, and try again.
You then need to restart OFM, you can use ofm restart to do that. The extension should then appear in the UI.
I think I may start from scratch with a fresh pi os image and then redo the extension installer.
I’m sure I must have messed something up along the way.
Just out of curiosity. Does the screen I shared with you match some previous version/fork of the extension?
I’m somewhat consoled that you, as the developer, are also perplexed about this behavior, since as a noob I’m definitely out of my depth, not understanding exactly which features come from which software modules, on what versions.
Speaking of which, could you verify that the firmware and py versions that show in the screen capture I sent before are what is expected?
Also, any way you could post a screen capture of what the sangaboard extension screen “should” look like with the multiple sliders?
Thanks so much.
Phil
FYI,
I reflashed my SD card with a fresh install of pi os openflexure image.
Reinstalled the sangaboard extension as per the instructions.
Same exact behaviors and appearances of the open connect app and sangaboard extensions.
Only one slider shows, and PWM frequency is still blank.
Same exact error messages showing in the open connect app log as before the rebuild.
( 6/15/2025 11:30:54 PM
ERROR: ‘Sangaboard’ object has no attribute ‘illumination’)
William,
Thanks for taking the time to provide this suggestion.
I went to the link on the openflexure sangaboard page that you included in your post. I opened the link to the sangaboard extension repo provided on that page. That is exactly the same repo and instructions that I have used on all my installations of the sangaboard extension installation attempts. Just to be exact, the SHA on that commit is 0ec6c9096398048665ccc61270a5df020d5c9478.
So, unfortunately, this does not provide a new avenue for my efforts.
I very much appreciate you providing your hints on this.
I’d really like someone to go through these extension instructions on a fresh pi os build and let me know their results. I’m just going around in circles. Maybe I’m doing something incorrect in my install procedure, but there are only a few critical steps, and I believe I have done them properly.
I’d be happy to be proven wrong on that score, believe me.
Best regards,
Phil
This still looks like the OFM server is not using the modified Sangaboard install for some reason, this is what you should see (sorry about the quality, my test setup has a touchscreen and getting a screenshot is awkward):
ofm activate #and then in that shell
python #and in the python shell
import sangaboard
sangaboard.__file__
with sangaboard.Sangaboard() as sb:
sb.illumination
Also check that there were no permissions related issues when installing the modified pysangaboard.
Filip,
Many thanks for your thoughtful and detailed response.
Now we may be getting somewhere.
I have never seen the slider arrangement that you show in your screen capture, just to be clear about that.
I ran your suggested python test and received both a “Module type illumination not recognized” and a ‘Sangaboard’ object has not attribute ‘illumination’. Please see my screen capture attachment.
These errors are now getting to what I believe is the crux of my problem.
You mentioned permission errors…
The pysangaboard setup did not run for me under the “ofm activate” environment without prefixing the command with “sudo”. I am so used to doing this on linux that it didn’t strike me as out of the ordinary. Perhaps using sudo in this case causes a context/environment shift that invalidates the install?
In this last install attempt, I started out with a brand-new openflexure pi os installation on my SD card. When I’m logged in as user “pi”, is there some procedure or script that I missed that is needed to elevate that user permission within OFM python virtual environment?
I assumed that the permissions section in your instructions only referred to the extension installation, and not the pysangaboard update, since it wasn’t mentioned in the instructions until farther along, so maybe I misunderstood that part.
Can you give me a step-by-step that includes preparing the “pi” user permissions as though this is all being done from a brand-new-out of the box installation of openflexure pi os, and assuming that the pi user permissions are incorrect out of the box?
Sorry to seem like such a noob, but I have only a vague understanding of how python permissions work in virtual environments, and am used to doing pretty much everything on linux as “sudo” (since the first release of redhat (hahaha)) (…I’m 65).
Please look over my screen capture and let me know how best to proceed.
BTW, I am so thankful to you, Filip, and those many, many volunteers who have put together such an accessible, quality, microscope. I have a life-long obsession with microscopy which has reared its pretty head periodically during my decades, and I discovered OFM at a time now in life when I can spend more time on this kind of thing, being semi-retired. When I get this one debugged, I am going to build another for my brother, who runs an organic grass-fed beef and gardening farm in Indiana, and is interested in following up on some of the recent research in soil microbiome health being promoted by the experts in sustainable agriculture.
Again,
Thanks for responding, and hopefully my growing pains with the illumination piece will be instructive to others who come later.
Phil
Thank you for the screenshot, that confirms that pysangaboard wasn’t installed probably because of the permissions issues. It is possible that I missed a permissions related step when I made the instructions, probably also doing something automatically. Using sudo might bring you out of the virtual environment. Please try the permissions fixing steps in the extension instructions:
sudo chmod -R g+w /var/openflexure/
sudo adduser pi openflexure-ws
and then log out and login and try the pysangaboard install steps again. If that doesn’t work you can try changing the permissions to 777 on the /var/openflexure forlder as a test, or sudo chown pi -R /var/openflexure/application/openflexure-microscope-server/.venv/
Filip,
I did another from-scratch installation of ofm pi os, and after all the auto-updates, performed the permissions changes you recommended, but “before” doing any of the pysangaboard pre-requisite updates. This time no sudo level was required, and the extensions screen and illumination operation are now working as expected! Thanks so much for your patience with me!!
The key change, as far as I can tell, was to run the permissions changes prior to the pysangaboard pre-requisite updates.
May I make a suggestion for improving your instructions?
Since there would be no harm to doing the permissions piece before any of this (in a worst case scenario it would just indicate that it is already done) and some benefit to just having this in a known state before any of the pysangaboard updates or extension installs, it seems reasonable to just put the permissions changes and logout and login right at the beginning of the instructions as a pre-requisite for the entire install, rather than as a “remediation” later in the instructions chain.
Also, based on my experience, it seems like doing the permissions after having gone through the procedure with incorrect permissions once actually poisons the environment for later install attempts. I could be wrong about this piece of it, but it appears that this is what was getting me stuck trying to reinstall things, even after I did the permissions as a “remediation”.
It might save some other poor sod like myself from having to go down this rabbit-hole in the future.
Again, Many Thanks and Keep up the Good (and I’m sure often thankless) Work of maintaining and improving this outstanding open-source project.
Phil
I tried installing this extension with the steps on GitLab. However, whenever move the stage the LED turns dim and the image becomes black. Setting the illumination percentage again doesn’t work and I need to restart.
