FLAPI - A Flashlight API

I'm trying to buid a flashlight, so in the process I thought of an API for the unit, since I believe that an open standard is better than a closed one, I put this work for consideration and ampliation, with the hope that someone likes the idea and helps me to make it better.

And since is open source, may be more manufacturers use it for the benefit of all.

Thanks

Pablo

# FLAPI a Flashlight API
#
# Original idea by Pablo Untroib
# Left on the Open Source the second after thinking of it
#
# Copyright (c) 2004 This API belongs to the common
# knowledge of the CPF forum
#
# This file is part of FLAPI
#
# FLAPI is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# FLAPI is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details: www.gnu.org
#
# Why an API you ask: because there are on the market microprocessed flashlights that with little
# or no modification can be user customized to do specific tasks.
#
# If you are a manufacturer and want to use this API you are free to do so, you must disclose
# which functions are implemented, but you're not obligated (but welcomed) to disclose the
# source code of your implementation
#
# This is the first attempt in my life to write an Application Programming Interface, I readed on the
# web about APIs before attempting doing this, but I saw no clear guidelines on how to do it, so
# I'll do it my basic way, in hopes that someone with more knowledge, straights it later.
#
# I will call this version 0.1 towards the final and polished 1.0

Part 1 - Flashlight hardware capabilities

Button (x)
X= defines how many on/off buttons the unit have

Selector (x)
X= defines how many selectors the unit have

ButtonSpec (x,y)
X= defines the characteristics of the button
Y= defines which button has the described characteristics
Examples:
X=1 on/off button
X=2 on/off button with momentary on/off

SelectorSpec (x,y,z)
X=2 2 positions selector
X=n n position selector
Y=0 the selector does not have pushbutton capability
Y=1 the selector have pushbutton capability
Z= defines which selector has the described characteristics

Sensor(x)
X=1 temperature
X=2 over voltage
X=3 low battery

Lights(x)
X= defines the quantity of lights available

LightSpec (x,y)
X=1 LED
X=2 Incandecent
X=3 HID
X=n to be defined
Y= defines which light has the described characteristics


Powerlevel(x)
X=0 Low level
X=1 Max level
X=n intermediate levels

Memory(x)
X= bytes available for programming storage

Part 2 - Flashlight functions definition

Pulse(x,y)
X= on time
Y= off time
Example
Pulse (5,3) If you want to send a 5 second signal followed by a 3 second pause

Strobo (x,y,z)
X=frequency
Y=on pulse width, must be checked for consistency against the frequency
Z= off pulse width, must be checked for consistency against the frequency

Signal (Pulse(x,y)….Pulse(xn,yn))
The signal will be componed out of pulses, for example a SOS signal is composed by joining 9 pulses.

Part 3 - Statements

To be continued

It seems to me that what we really need is an open-source codebase for CPF flashlight creators. We as a community can all contribute to such a codebase.

Both Arc and HDS have stated flatly that they will not open source their code. Without an open codebase, I don't see what benefit we would derive from their adhering to your API.

I believe that an API serves the end user as well the manufacturer, I mean, if the user knows how to make his light work the way he wants he has a better flashlight.

I found this way a better way to implement the different needs of flashlights users.

See for example what Peter G. is trying in his forum, to agree on a simpler way to use the arc4, I wish him the best of luck, but its very difficult to agree to what is simple for all.

I don't think this "in progress" API will help in the inmediate future, but it can be used in future designs.

Think of the implications:
- 3rd party add on software modules for your light
- more functions
- modders will have more functionality by adding a second button
- open versus close

Pablo

I still don't understand. As long as Peter / HDS are producing lights with closed-source firmware, how does the API help anyone? How can functions be added?

Third party add-on software modules for closed-source flashlights? What's next, flashlight viruses? /ubbthreads/images/graemlins/wink.gif

I agree with Geek, the only thing that makes sense is a fully open codebase for use in modder flashlights, along with a reference hardware design. If the codebase is GPL'd, I'd be up for contributing to it.

FLAPI doesn't IMO make that much sense, because I'd like to see all kinds of interesting new interfaces that don't fit into predefined models all that well.

From other threads, it appears that there are a number of CPFers who are experienced in coding for microcontrollers. I don't know how my own skills would compare, but I'd enjoy contributing to an open source codebase. I've been thinking about suggesting this project, but didn't know if there would be adequate interest and support to make it worthwhile.

We'd definitely need a good reference design for the hardware and someone willing to manufacture them. Microcontrollers are flexible enough that the same "motherboard" should be able to support user interfaces that differ both in hardware and software.

[ QUOTE ]
Third party add-on software modules for closed-source flashlights?

[/ QUOTE ]
yes, why not, think of photoshop, its closed source, yet there is available plugins for it.

It would be great to have a reference hardware, but that is not my area of knowledge.

May be this helps toward that goal, in its actual form or in another, I'll be happy either way.

Pablo

Who says you have to use this FLAPI with an Arc4? Why not build your own light from the ground up using FLAPI programming...

> think of photoshop, its closed source, yet there is available plugins for it.

Modern computer operating systems have elaborate systems to allow separate codebases to interoperate without exposing their proprietary internals. I'm not aware of anything analagous for microcontrollers.

If you wanted to add a feature - say, a strobe function - to a light like the Arc4, I'm relatively sure this would have to be hacked into the firmware's own codebase - again, not possible since Arc is keeping their source closed.

Are any microcontroller hackers or flashlight modders interested in pursuing an open-source microcontroller flashlight platform?

I think different kinds of boards will be needed depending on the form factor of the flashlight it's made for, the voltages available, desired features, etc. For example, in an LED light, the microcontroller and the DC-DC converter probably want to be on the same board, and the DC-DC converter will be different depending on the LED and battery configuration. Rather than aim at total generality, we should probably choose one general class of light, e.g. something vaguely Arc4-like, or something vaguely Eternalight-like, or a large lantern, whatever.

From my point of view (as a programmer), software is the easiest part of this vision. The middle part is the electronics, and the hardest part is the mechanical construction (machining or molding or whatever).

Features to think about:

1) standard user interface stuff including PWM dimmer for LED's or PWM regulation and soft start for incandescents
2) Lithium ion charging control
3) Temperature and voltage sensors for power management (dim the light if batteries get weak or if the light gets too hot)
4) Computer interface for user up/download of code and parameters
5) Active cooling (temperature control) in larger flashlights

Any more stuff?

[ QUOTE ]
Who says you have to use this FLAPI with an Arc4? Why not build your own light from the ground up using FLAPI programming...

[/ QUOTE ]

I certainly not /ubbthreads/images/graemlins/smile.gif
What I said about the ARC4 was the poll PG is having right now about simplyfying usability.

I'm trying to create this kind of light, but if its not possible to do via an API I'll use the modular aproach, I mean you have x mem, you can load modules A, B & C and left out modules D to Z.

I want a light to be user accesible via PC, this can be definitelly done, and if not by me, will be by others in no more than a year, I can bet you a beer!

Pablo

> ..use the modular aproach, I mean you have x mem, you can load modules A, B & C and left out modules D to Z.

Yes - I was thinking this, too. A company like Arc could make a modular firmware if they wanted. (Actually, we could do this with our hypothetical open source firmware, too.) You could go to their website, choose the features you wanted (A, B & C), and their server could compile the appropriate instructions into a custom firmware you could then download to your PC. You'd need a special cable to connect the flashlight, of course, whereupon you could use a simple app to re-flash the firmware. Arc could do this to make their lights customizable without opening their source. We could do this to enable the average user to tweak their light withhout having to customize and compile the source code themselves.

It should be trivial to allow the end user to adjust preferences in or view statistics from their light by connecting it to their PC. Many modern microcontrollers incorporate serial communications in their hardware. Most of it is RS232, though you can get onboard USB nowadays, too.

Geek, finally ! /ubbthreads/images/graemlins/smile.gif

Thats my vision, to customize the light for your needs, using the method you like, but being able to choose your preferred functions!

In another thread I described with more detail the hardware plataform I'm planing to build.

I want this light to see the light /ubbthreads/images/graemlins/smile.gif

Pablo

I don't see much need for yet another 1x123 1 watt light. The Arc4, 2 stage Firefly, Longbow Micra, etc. all do a real nice job of that. Also, it's hard to build the metal parts of something that small, with the kind of user interface flexibility we'd like.

I'm imagining a bigger light, about like a Tigerlight FBOP but maybe a little bit shorter. It would have three 18650 lithium ion cells in a triangular config in series, and a 5 watt Luxeon in a large, fixed reflector. It might have a secondary 1 watt flood emitter on the side (McGizmo did something like that with a Pelican M6 once and it came out real nce). It would have one or two pushbuttons and be continuously dimmable by PWM, like the Photon Freedom. The CPU would also act as a charge controller so you could fast-charge it directly from 12 volts. That would let you use a cig lighter adapter for in-car charging, or a PC power supply for fast charging at home. The large diameter would make it fairly easy to assemble the light including pushbutton switches on the side, I'd hope.

so basically you're saying no more innovation for small flashlights?

c'mon its more fun to have new ideas around...

Pablo