The old ShiftPWM page

ShiftPWM is a software PWM library for Arduino. It uses the SPI to drive shift registers in the most efficient way possible. This makes it possible to control 768 LED’s at 32 brightness levels for a fraction of the price of dedicated led drivers. Code for HSV to RGB conversion is included for easy color shifting.

ShiftPWM rainbow on a breadboard

The LED rainbow from the ShiftPWM example

What is ShiftPWM?

ShiftPWM is a library for Arduino to control many PWM outputs using shift registers (for example the 74HC595). I wrote it for my job at the Electronics Atelier of Industrial Design at the Technical University of Eindhoven, where I often got the request to individually control the brightness of many LED’s.

The dedicated IC’s for PWM, for example the TLC5940, are expensive. Generating the PWM in software costs a few CPU cycles, but allows you to use much cheaper hardware. ShiftPWM does this very efficiently, allowing you to control up to 768 outputs with ease.

ShiftPWM computes the outputs in a timer interrupt and uses the SPI to control the shift registers as fast as possible.

Features of the library:

  • Control the duty cycle of many PWM outputs in a single shift register chain.
  • Easily configure frequency, number of registers and number of brightness levels.
  • Outputs can be inverted for common anode RGB LED’s
  • Function to print information on timer settings and interrupt load to the serial port.
  • Switches to timer2 if timer1 is in use by the servo library
  • Checks for input to functions that is out of range and prints error messages to the serial port
  • Can be placed in the libraries directory of Arduino
  • Includes an example which can be opened in Arduino via file->examples
  • Example includes HSV to RGB function for easy color shifting with RGB LED’s.

How fast is ShiftPWM?

ShiftPWM computes and transfers the bits for one shift register in just 43 clock cycles. The load on your program can be calculated by the following formula:

  • Load = Interrupt frequency * interrupt duration / clock frequency
  • Interrupt frequency = PWM frequency * number of brightness levels
  • Interrupt duration = 112 + number of shift registers * 43 clock cycles.
  • In one formula: L = F*(Bmax+1)*(112+43*N)/F_CPU

Here is an example of the load on a 16 MHz Arduino Uno:

Shift registers Maximum Brightness PWM Frequency Load
3 255 75 Hz 0.29
6 255 75 Hz 0.45
24 100 75 Hz 0.54
48 64 75 Hz 0.66
96 32 75 Hz 0.66

 

Where can I get ShiftPWM?

ShiftPWM is hosted on Google code here.

You can download an archive which you can extract in your Arduino libraries directory:

Download link on Google code

New version moved to GitHub, extract to Arduino-1.0/libraries/ShiftPWM:

Download an archive of the latest release

11-05-2012: New version on GitHub has easier to use RGB and HSV functions, support for gaps of unused pins (offset), pin grouping (RRRGGGBBBRRR… instead of RGBRGBRGB), an option to not use the SPI (2.5x slower) and new examples. Documentation will be updated soon.

 

How do I use ShiftPWM?

The easiest way to get started with ShiftPWM is to start from the example that comes with ShiftPWM:

  1. Download ShiftPWM from Google code
  2. Extract the archive in the library directory of Arduino.
  3. Restart Arduino
  4. In Arduino, go to File -> Examples ->ShiftPWM

Which hardware is used with ShiftPWM?

Basically just an Arduino and a chain of Shift registers. The circuit is almost the same as in the ShiftOut tutorial on arduino.cc, but it uses pin 13 as clock and pin 11 as data. You can choose the latch pin yourself, but the data and clock pins should be connected to the SPI pins MOSI(11) and SCK(13). Leave out the latch pin capacitor!

High power led driver

I have designed a ShiftPWM compatible LED driver to drive 3W RGB LED’s. It has 6 STP04CM05 LED drivers, so it can drive 24 channels at 350 mA. That’s a total of 8A per board, but of course they can be chained. I use 3 of them in my Ambilight project go get 24 independent 3W RGB LED’s. The maximum LED current can be set with a potentiometer from 60-350 mA. I designed them for my own project, but I am considering getting a small batch (100) made to sell. Let me know if you are interested.

My 24x 350 mA LED driver with an Arduino Uno for size comparisson.

What’s in the example?

The example that comes with ShiftPWM demonstrates the use of all ShiftPWM functions. It also includes a function to convert HSV to RGB to make it easier to work with RGB LED’s.

Here is a video of the example with 16 RGB LED’s:

Function overview

The library provides the following functions:

ShiftPWM.Start(int ledFrequency, int max_Brightness)

Enable ShiftPWM with desired frequency and brightness levels.

ShiftPWM.SetAmountOfRegisters(int newAmount)

Set or change the amount of output registers. Can be changed at runtime.

ShiftPWM.PrintInterruptLoad()

Print information on timer usage, frequencies and interrupt load.

ShiftPWM.SetOne(int pin, unsigned char value)

Set the duty cycle of one output

ShiftPWM.SetAll(unsigned char value)

Set all outputs to the same duty cycle

ShiftPWM.OneByOneFast()

Fade in and fade out all outputs fast

ShiftPWM.OneByOneSlow()

Fade in and fade out all outputs slowly

ShiftPWM.SetGroupOf2(int group, unsigned char v0, unsigned char v1);

ShiftPWM.SetGroupOf3(int group, unsigned char v0, unsigned char v1, unsigned char v2);

ShiftPWM.SetGroupOf4(int group, unsigned char v0, unsigned char v1, unsigned char v2, unsigned char v3);

ShiftPWM.SetGroupOf5(int group, unsigned char v0, unsigned char v1, unsigned char v2, unsigned char v3, unsigned char v4);

Set a group of outputs to the given values. SetGroupOf3 is useful for RGB LED’s: each LED will be a group then.

Assumes that all groups are size x for the function SetGroupx.

Gallery

If you used ShiftPWM to create something cool, please send me a link to a video. I will create a gallery page to show off all the cool projects.

Support

Please ask support questions in the Arduino forum here

62 Comments

  1. I was constructing a board to run 24 3w rgb leds using constant current drivers, but your board design seems to be much more compact and cheaper to manufacture. Could you post your schematic file on google so i could see the general layout of your ic’s since i am unfamiliar with those chip drivers. Also, are the capable of running all 4 channels at 350 mA steady?

    • The board has 24 PWM channels, so it can drive 8 3-pin RGB LED’s at 50 to 350 mA, settable with a potmeter.
      The biggest issue is heat, therefore i power the board from a 5V PC power supply -> huge diode -> board. The board has to dissipate 0.7V less that way.

  2. Do you have the wiring schematics for the circuits used in your example videos??

    • It’s on my to do list, but I have been terribly busy lately. All LED’s go with a resistor to the shift register outputs and share a common anode (V+). You will have to calculate the resistors per color, being (5V-Vfw)/20E-3A. For a Vfw=2V, this would be 150 Ohm.

      The shift registers are in one long chain. From pin 0 of registers 0 to the last pin of the last registers the outputs are RGBRGBRGBRGB…

  3. Do you have a rough idea how hard it would be to rearrange the data format in such a way that the LEDs can be addressed as RRRRRRRR – GGGGGGGG- BBBBBBBB etc. This would allow to use constant current drivers and hardware color balancing.

    • I redesigned my high power led driver to have adjustable current per color, so I will update the library soon to have this option.
      Somewhere next week I’ll upload a new version.

      • I figured it out. Didn’t work at first, as I was doing the math wrong. I’ve attached a youtube link for the ‘gallery’.

        • Hi Robert,
          Your video looks great! I’m wondering if you wouldn’t mind sharing the code with me? I am up against the same dilemma in a project that I am working on.

          Best,
          Sarah

          sarah.bearse@gmail.com

          • Hi Sarah, I’ve just seen your question.

            You can find all of my code/layout related stuff on Github.

            http://www.github.com/madworm/

  4. Hallo Elco,
    Ik heb je gevonden via Serge Offermans, een collega van de TU. Hij vertelde me dat je pwm library sneller is dan de library voor de tlc5940. Klopt dat?
    Ik wil een pov project doen en de tlc5940 is een beetje langzaam daarvoor.
    Groeten,
    Rob

    • De library is in ieder geval een stuk vrijer te configureren. Je kunt zelf de PWM frequentie kiezen en het aantal brightness levels. Hierdoor kun je ook hele hoge frequenties nemen met een beperkt aantal brightness levels in plaats van de default 4096 van de 5940.

  5. Just wanted to post my project that makes extensive use of the ShiftPWM library. It’s an RGB scoreboard specifically for Ultimate Frisbee games. The entire display is being controlled by 11 daisy chained 8-bit shift registers. Thanks for the great library!

    [youtube http://www.youtube.com/watch?v=Q-YWABsCgqs&version=3&hl=en_US&rel=0%5D

    • Very impressive build Tom! Rigid case and very user friendly interface. Do you match the LED’s to the players’ shirt color?

      • Yes… that’s the plan. Before the game starts you can match the colours to what’s on the field. The only thing I haven’t quite figured out is what to do when one of the teams is wearing black. 😛

        Tom

  6. ELCO!

    Firstly, thanks so much for the use of this library, it’s made my deadline far less intimidating.

    I’m a long way from achieving what I set out to do, but finished building the hardware today and implemented a basic code. More will come by Wednesday when I install in a window in Mayfair. I hope to achieve the effect of raindrops falling into a puddle.

    Thanks again, I’ll keep you posted with developments.

  7. The finished article. Thanks again for sharing.

  8. Hi,

    I was wanting to know how, if possible, to switch from using timer2 to timer1?

    Thanks,
    Nick

    • Hi Nick,

      Timer1 is the default. Only if servo.h is included, it switches to timer1.

      Elco

      • So you use pins 9 and 10 on an uno? because you say to use 11 and 13.

        Thanks again,
        Nick

        • Why would they be different? I say its 11 and 13, because it is 11 and 13. The MOSI and SCK pins. The timer outputs are not used, the timer is only used to generate an interrupt.

  9. Hi thanks, Do you know if there is a way to not to use 11 and 13? I am trying to make an led controller with dmx inputs and this also uses the same pins for the timer.

    • I am also interested in using other pins. How would I go about changing pins 11 and 13 to pins 5 and 7. Since you are using MOSI, I assume we would have to include SPI.h.

      • I have e-mailed you the version without SPI, because I don’t have time to update the website at the moment.
        Because it doesn’t use hardware SPI, you don’t have to include SPI.h and it is 2.5x slower.

  10. Hi, thank you for the excellent information! I am working on a 100 RGB LED display and have been searching every where for help and then I found your article. Awesome. If I understand the math correctly (I may not) I’ll need 39 595’s to run these 100 LEDs. Is this correct?

  11. Elco, thank you for the confirmation of my math (that darn 9 is right next to the 8…) I checked out your friends clock, he did a great job on it. I really the the concept behind it.

    When I finish my project I’ll try to post it. Don’t really know how to do that yet, first need to concentrate on my project.

    Again, thank you for all the great info on this site. I know it takes a lot of time.

  12. Hi,

    GREAT STUFF!!!
    I am working on animating wire framed LED displays. I want to use ShiftPWM as well as control 16 separate relays(on/off) with Vixen. Could any one point me in the right directions

    • You could use ShiftPWM for both if that’s easier. You can switch the relays by writing zero of maximum brightness. A PWM value in between would not work, because the relays are too slow for that. Switch the relays with a transistor and use a diode in reverse parallel to the relay coil to protect the transistor from induction currents. I use relays in my UberFridge project, so look there for schematics.

      For your LED displays, you will probably want to place transistors behind the shift registers.

  13. Hi Elco
    thanks for the code, just getting my head around it. I’m unfamilar with some of the terminalogy and in pariticular load. I’m interested in understanding if running this code will allow me to do other stuff in the main loop and how much your code will effect this, it seems to me that a load of 0.66 means that for the rest of the time I can do stuff and that you code will not effect this, is that correct? Not sure what 0.66 refers to but assume that its a percentage for time taken in the cpu. (i was thinking of putting in capSense hence my question)

    • You are correct. By a load of .66 I mean that the CPU will be busy with the ShiftPWM interrupt 66% of the time. The capsense function would be interrupted by ShiftPWM, but I don’t expect this to be a problem if the interrupt frequency is fast enough. It will just make the charge time measured by CapSense faster.

      • Thanks for that Elco
        that makes it a lot clearer 🙂 Look forward to using the code.

  14. Good-Day to you Elco !

    1st things 1st – YOUR A GENIUS !!!!!!

    VERY VERY impressed at the creativity and know-how it took to put this all together! Ive only started learning electronics after 20 YEARS of avoiding it as the level of technology was so very LOW (compared to star-wars/star-trek space-ship-future-tech, lol) but now that arduino’s are bringing us all closer to world domination & control of tasty control of the environment around them they have totally got me once again focused on learning more!

    I wish to create an array of 80 RGB LED’s with your awesome code but would like to build this all on breadboard 1st (finally got myself 10 x 820 tie-point breadboards, china, lol) and just waiting on parts (10 x shift registers, IC sockets etc) but i cant find a link of a schematic of how i can get this all onto a breadboard, Please please please could you direct me to the right place as ive been searching for a few weeks now, lol, and still cant find it !

    Also i have a few RBBB arduino clones, would this work with the spartan RBBB board ?

    RBBB Arduino:
    http://shop.moderndevice.com/products/rbbb-kit

    Many thanks in helping me to show me how to wire this up to a breadboard and once again, Damn GREAT work with this AWESOME hack !!!

    Keep up the Brilliant Work !!

    kind & best regards,

    Anil Sethi Jnr

    • The RBBB arduino should be fine. For 80 RGB LED’s, I would just chain 10 shift registers together, like the Arduino ShiftOut Page. (see link on this page). Just remember that I use different control pins and no latch pin capacitor. You should add resistors for your RGB LED’s. On 5V R 150, B 100, G 100 ohm should be fine.

  15. Hello,

    I’m trying to light six RGB LEDs from three 595s. I seem to be having brownout issues, with the pro mini 3.3V. This is my first time using the pro mini 3.3 so I’m not sure what to expect, but I can only seem to light 9 of 18 LEDs at once. Each LED draws 20mA at 2V, 3V, 3V for RGB respectively. Have I hit the max output limit, or is it because I’m powering from USB?

    • Hi Jamie,
      Most USB ports can source 500 mA. With 18 LED’s, it should just work. But at the start of each PWM period, all LED’s turn on at once. This gives a fast power surge and your USB port might not be able to keep up with the sudden change in current, causing a voltage drop and an Arduino reset.

      If you are powering your LED’s from the 3.3V line, the same applies for the 3.3V regulator. Maybe switching to powering the LED’s from 5V, with different resistors, might help. I have a board with 6 shift registers, 16 RGB LED’s, which runs fine from USB. But that will depend on your PC. You could try a phone USB charger. They usually deliver 1A.

      You should always at least have a big capacitor on the LED supply line as a buffer for sudden current increases.

  16. Thanks Elco,

    I’m new to EE, so my problem is probably with my wiring. My Arduino hasn’t reset due to power.

    Where does the capacitor go in my circuit? Is it between my Vcc out on the mini and Vcc in to my registers? What size would I need?

    I’m curious, how is it possible to power so many LEDs from a single serial pin out? Where does all the current come from? Sorry if that sounds silly, electricity is weird, it’s hard for me to wrap my head around some of the concepts.

    Cheers

  17. Hi Elco,

    Sorry to bug you, no rush, but I tested the line voltage and during the one-by-one function, the voltage is around 3V, then when it lights all, the voltage drops to 0.8V. I’m using a 9V 650mA source into the raw input. Any ideas? This same circuit works just fine on my UNO.

    Thanks!

    • See, that is the problem. The power supply or the voltage regulator cannot keep up.
      The power to the LED’s should come from a powerful enough source, so that it won’t drop in voltage when a lot of current is drawn. If your Arduino is powered from the same source, it will reset. It might not, because it can switch to USB power.

      If you are using LED’s with a common positive supply, the power to the LED’s should come directly from your power source. If your LED’s are common ground, your power source should power the shift registers. The 595’s cannot handle 9V, so you need a regulator like the 7805.

      The capacitor should be at least 100uF and should be between VCC and ground. Think of it as a local battery. And just to check: you did connect all grounds together, right?

      • Hi Elco,

        Thanks for your help! I think I understand what you’re saying, the LED power source (including the 595 Vin) should come from a stronger source than a pin set to HIGH from the arduino. Makes sense, so the serial input does not contribute to the powering of the LEDs, but rather the Vin?

        Fact is, I think I just have some shotty wiring, but I’ve learned a lot here, thanks!

        • Oh hell yes, didn’t think you would go that far!
          A digital pin can only deliver 30 mA!

  18. Will this work with a tpic6b595?

    • I think it will. You might need to invert the latch signal or choose a different SPI mode, but it should work with any shift register.

  19. Does a 75 Hz refresh rate and 255 PWM steps translate to a ~13 msec period and PWM “step” intervals of ~52 usecs per LED?

    • Yes that’s correct.

  20. hi , i am building a one color led array of 256 , i know shiftPmw is not intended for that , but i like the IRQ idea , where you can still process and draw in the same time ,

    the array is ok , the only problem i have is that when a led is supposed to be dimmed , it is blinking instead
    so i thought it would be a noise problem , but i made a really nice ground plane (it is my 2nd prototype)

    i dont know what i am missing here , maybe some capacitors ?

    can you give me some advices ? thank you.

    • That could be a lot of things. Are you using the ShiftMatrixPWM beta code?
      You should definitely add big capacitors to all your power lines, because you are switching high currents. Check your power with an oscilloscope if you can. Otherwise a multimeter. It could be that you have a drop in power when all the LED’s switch on. Check with only one LED on as well, since that is easier on your supply.

      • i didn t knew about the code version , so i am updating the arduino ide and the library version to be sure .

        i dont own a oscilloscope ,

        but now that i think about the power supply ,
        there is maximum 32 led light up at the time , they drive 20mA each
        0.2*32 is over 6A (my power supply is 6A max ) (plus powering the arduino and all the 595)

        so that might be the issue
        thank you for your help , i ll make a bunch of tests and tell you about the result

        • The matrix code is not posted here, but you can find it in the ShiftPWM topic on the Arduino forum if you log in.
          It’s better to power the Arduino from a separate power supply or USB. Big capacitors >100mF on your power lines are a must.

          • hey , i realized i was off on my intensity calculation , it is 640mA not 6.4A my board is driving , so , i am way on the green on that .
            i also tryed a realy stabilised ATX power supply , same problem ,
            i have tryed a 4mf at the power line , still the same
            and also i updated the library and IDE ,

            and for the power supply i am using , it is a realy nice one , well stabilised , quite expensive , so i am confident that it is not the problem ,

            but i will try a bunch of different code , to see if the problem persist on the matrix or it depends on the code

            i ll keep you updated , thank you !

  21. Elco,

    I’m attempting something similar to LineKernel – a 6×12 RGB LED table (216 outputs, 27 shift registers). When you say tie a 100mf cap to all the power lines, do you mean all Vins? Both 10 (MR) and 16 (Vcc) are tied to 5v on the 595, am I supposed to have 54 caps? Or just one cap between the original V+ coming off my LED power supply and ground?

    I’ve got a 9v supply for the atmega and a 2A 5v supply for the LEDs. Is it correct that i should tie the 9v+ to the atmega, the 5v+ to all the shift registers, and both grounds together?

    The shiftregisters will be mounted in groups of three, distributed across the bottom of the table, max 1ft apart. Do you see any other conceptual problems with this application?

    Awesome work on the library, your involvement in the development community is amazing and gives us noobs a fighting chance at making cool stuff. Thanks!

    • Hi Joe,

      Are your LED’s common cathode (1-, 3+) or common anode (1+, 3-)?
      For common cathode, your output pins are powering the LED’s, so the VCC pin of the shift registers should have a capacitor.

      For common anode, the shift registers are sinking and a 5V power line powers the LED’s. That line should have some capacitors.

      Your connections sound correct. Best is to power the shift registers from the Atmega 5V, not the same supply as the LED’s, if your using common anode. Add some caps here too.

      54 caps is overkill, just make sure that your 5V line has some caps and that they are a bit distributed over your line.

      But another concern, 216*20 mA = 4320 mA. Just a bit over the rating of your supply, when everything is full white. Might be okay, but measure that.

      And did you already order shift registers? Using TLC5916’s might save you soldering 216 resistors…

      • gaaahhh i typed this out and it got deleted. grumble grumble grumble

        When i bought them on ebay, they said common cathode. to run shiftpwm_example, i have to set invertoutputs to 0. is that indicative of one of the other?

        i’m confused by your third paragraph. don’t the shift registers power the LEDs? So how could you separate the power source for the two? Looking at this schematic
        http://arduino.cc/en/uploads/Tutorial/ShftOut_Schm1.gif
        +5 will be tied to my 5v source (with the caps), and data/clock/latch will be tied to the ATmega, which will be tied to my 9v source, and all grounds will be tied together. Sorry if i’m just rehashing what you already said.

        When i tested these LEDs at 100 brightness, they were only driving ~10mA per pin, which should put me around 2amps. This leads me to another question – how are the brightness limits selected? When i set the numregisters to 27, no LEDs will light with a maxbrightness of 255. Similarly, for a maxbrightness of 100, LEDs won’t light up with a SetOne brightness argument of 255. BUT with a maxbrightness of 100 and a SetOne brightness of 100, they don’t appear dimmer than normal but draw less current… let me know if i’ve got some fundamental misunderstanding.

        I already bought the 595s, but theyre cheap… which is why i bought them in the first place. and if i switch to 5916s i wont be able to use your badass library 😛

        • -To recover text from input fiels when you accidently close a page: install the Lazarus addon (firefox..)
          – Common cathode means indeed that the shift registers are powering your LED’s, no separation in supplies. The 3rd paragraph only applies to common anode LED’s
          – Max brightness sets the number for brightness levels. What you set as maxBrightness is fully on.
          – Calculating the PWM values takes time. Too many pins * too many brightness levels takes too much time. Your interrupt load will be too high. This will be printed on the serial port. So maxBrightness determines the resolution, not the actual brightness. Choose something that gives a load under 0.70, or your processor will spend too much time in the interrupt.
          – The TCL5916’s are just shift registers with a constant current sink output, they work great with the library.

          • Ohhhh that makes a lot of sense. Thanks for the explanations!

  22. Hi Elco,

    Your work is excellent! I’m trying to use shiftPWM on a 2D RGB LED matrix of size 8×16. Where can I find the ShiftMatrixPWM code?

    • Sorry for my late reply. I am working on a big update for my website which will include more schematics, updated library, web shop and the matrix code. I want to do a bit more testing before officially releasing it. You can find the beta version on the Arduino forum topic when you login.

  23. This library is really awesome…thanks for creating it!

    One thing I was wondering, how would you approach putting a “mode” pushbutton in your example code?

    One where a user could push a small momentary-contact button to change the display mode. Like from the fast rainbow to slow, then maybe fade in/out by two, etc. Many of these patterns use loops to complete, so embedding a button check becomes a bit more complex.

    I’ve assembled the small button/resistor circuit tied into Pin 2 on the Uno and would like to add it into the example script to switch the modes.

    Thanks again for all the hard work…

    • An example with non-blocking fades is something that many users would want, so I programmed for a few hours today to convert the standard example into a new non-blocking one. This version uses no delay loops, but uses the millis() function instead.

      This example let’s you set the mode from the serial port. Using a button is a small change. I think it is exactly what you are looking for.
      I will add a video and update the documentation later, but the code is already available on GitHub. If you find any errors, please let me know!

  24. Hi Elco,

    I’ve got 4x 74HC595s for a 4×4 matrix. I’m trying to use your shiftMatrixPWM library but I am confused why there are 2 latch pin connections: “const int ShiftMatrixPWM_rowLatchPin=8;” and “const int ShiftMatrixPWM_columnLatchPin=9;”. I have one 74HC595 for each RGB colour and one for the common anode. Hence I have a data, latch and clock signal to be connected to the Arduino.

    Could you please explain how the columnLatchPin and rowLatchPin should be connected?

    • The matrix code uses two chains of shift registers: one for the rows and one for all columns. I do not use separate shift registers for each colors.

  25. Everything seems to be around controlling LEDs. How does this work with motor controllers? Any limitations?

    • Yes should work for motors as well, no problem. You do have to add protection diodes for reverse currents (motors are inductive). If you want the motors to work in both directions you need to use H-bridges instead of a single transistor. You can use the ShiftPWM outputs as the direction pins by just setting them to 0 or 255. Two direction pins and a speed pin will allow you to control the motor in both directions and with PWM.

Trackbacks/Pingbacks

  1. TIMO TOOTS | Elektron - [...] custom scripts, ShiftPWM library, EasyTransfer [...]
  2. Final Project: Laser Tic-Tac-Toe « Physical Computing – Tom Simmons - [...] pulse with modulation (PWM) across both. The library used is called ShiftPWM and can be found here. The actual…

Leave a Reply

Your email address will not be published. Required fields are marked *